# Cash App

> Documentation for Cash App

---

# Cash App Documentation

Source: https://developers.cash.app/llms-full.txt

---

---

# Getting Started

{/* 
 <div style="width:87%;">
  <div 
      style="
          display:flex; 
          flex-direction:row; 
          justify-content:space-between; 
          background-color:#00D64F; 
          border-radius:16px; 
          margin-bottom: 10rem; 
          align-items:center;
          max-height: 190px;
      "
  >
      <div 
          style="
              display:flex; 
              flex-direction:column; 
              gap: 4px;
              padding-left:48px;
          "
      >
          <h1 style="line-height: 38px; font-size: 38px; font-weight: 700">
            Get started with Cash App Afterpay
          </h1>
      </div>
      <div 
        style="
          display:flex;
          justify-content: flex-end;
          transform: translateX(30%) translateY(35%);
          flex: 1 0.5 260px;
        "
        >
          <img 
              src="../../assets/images/header - commerce entertainment hero.png" 
              alt="cash-app-afterpay-landing-hero" noZoom
          />
      </div>
  </div> 
  */}

## What is Cash App Afterpay?

Cash App Afterpay lets your customers make purchases and pay for their purchases over time. When customers pay each installment on time, using Cash App Afterpay is free.

Some customers qualify for Pay Monthly, which offers credit with interest payable between 3 to 24 months.

<Note>
  Cash App Afterpay is for US merchants and partners only.

  If you're a merchant operating in Australia, New Zealand, or Canada, see [Afterpay](https://developers.afterpay.com/docs/api/welcome/getting-started). If you're a merchant operating in the United Kingdom, see [Clearpay](https://developers.clearpay.co.uk/clearpay-online/docs/getting-started-with-clearpay-online).
</Note>

## Why use Cash App Afterpay?

**For merchants:**

* We pay you upfront and take on all credit and fraud risk
* We help raise your Average Order Value (AOV) and conversion rates by increasing purchasing power
* Customers look to Cash App Afterpay to discover new brands, providing merchants with a valuable source of new customers

**For customers:**

* We split the total order amount into four installments, taken automatically every two weeks
* It’s free and simple to join - just download the app, then set up an account in minutes. Eligibility criteria apply
* There is no interest with Pay-in-4 and no fees when customers pay on time. Customers who qualify can use Pay Monthly, where payment is spread over 3, 6, 12 or 24 months with interest.
* Customers can use their Cash App account to pay for purchases in four installments

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cash-app-afterpay-landing-2.png" alt="cash-app-afterpay-landing-content" noZoom />

## How is Cash App Afterpay different from Afterpay?

In the United States, Afterpay is now called Cash App Afterpay. It's available to both Afterpay and Cash App customers through a single checkout experience.

For merchants who previously offered Afterpay to US customers, Cash App Afterpay has a different logo and small changes to the Afterpay messaging on your product and checkout pages. There aren't many changes to your backend operations, payment processing, settlement, or other technical processes.

<Warning title="Important">
  If your app uses an explicit allowlist of Afterpay domains, you 

  *must*

   add 

  `api.cash.app`

   and 

  `cash.app`

   to the allowlist.
</Warning>

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/content - showcase messaging2.png" alt="Checking out with Cash App Afterpay" noZoom />

### Migrate to Cash App Afterpay

If you're an existing US merchant who needs to migrate from Afterpay to Cash App Afterpay, see instructions [here](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay).

---

# How are Cash App Pay and Cash App Afterpay different?

**Cash App Pay** is a payment method that allows customers to pay for goods or services in a single transaction.

**Cash App Afterpay** is a payment method that lets customers pay for goods or services in installments.

### Cash App Pay

Cash App Pay is a digital payment feature. It allows users to make secure, contactless payments in stores or online directly from their Cash App balance or linked bank accounts. Cash App Pay is an e-wallet primarily used on mobile devices, though it can also be accessed on a desktop or laptop.

### Cash App Afterpay

Cash App Afterpay is a buy now, pay later service that allows both Afterpay and now Cash App customers in the US to purchase goods and services online and pay in installments.

The Pay-in-4 feature allows customers to pay with four interest-free installments paid every six weeks. For example, if a customer buys a $100 product they make the first $25 installment at the time of purchase. Then they make three further \$25 payments at two-week intervals.

Cash App Afterpay is only available to US merchants. In Australia and New Zealand, our buy now, pay later solution is called Afterpay. In the United Kingdom, it is called Clearpay.

---

# Cross Border Trade

Cross Border Trade is a feature that enables you to accept Cash App Afterpay orders from international customers.

For example, if you have a US online store, you can accept orders from customers in Australia and those customers can use Cash App Afterpay.

* Click [here](https://www.afterpay.com/en-US/cross-border-trade) for an overview of Cross Border Trade for merchants

<Note>
  Afterpay customers can still make CBT purchases. Cash App customers that are new to Afterpay will not see options to use CBT.
</Note>

## Available Countries

The available countries for Cash App Afterpay Cross Border Trade are:

* Australia

* Canada

* New Zealand

* United Kingdom (as Clearpay)

## Setup

All Cash App Afterpay merchants have Cross Border Trade enabled automatically.

## Actions

Please ensure that your store is configured to meet these requirements:

**Currency**

Check that your store currency matches your Cash App Afterpay merchant account region. For example, if you have a US Cash App Afterpay merchant account, then your store currency must be set to USD. If the two do not match, Cash App Afterpay will not work.

**Store Address**

Check that your store address matches your Cash App Afterpay merchant account region. For example, if you have a US Cash App Afterpay merchant account, then your store address must be set to United States.

For information on how to set or change your store currency or address, go to the [Platforms - Quickstart](/cash-app-afterpay/guides/platforms/platforms-quickstart) topic and choose your platform from the list.

**Shipping**

You must configure shipping methods to any countries that you want to offer CBT to. So for example, if you have a US store and offer CBT to New Zealand, you would need to configure shipping methods for New Zealand within your platform's shipping settings. If you do not do this, international customers will not be able to place an order.

## Settlements

Settlements from Cash App Afterpay are always paid in your local currency. So, if you are a US merchant, your settlements are made in US dollars.

## Restrictions and Costs

You cannot display Cash App Afterpay messaging on the product pages for currencies other than the default store currency. This is due to possible exchange rate variations, which could lead to inaccurate installment amounts.

Cash App Afterpay charges a small additional fee on Cross Border Trade transactions. For details of this fee, see your Cash App Afterpay contract or email us at:

* [na-afterpay-merchant-admin@squareup.com](mailto:na-afterpay-merchant-admin@squareup.com) - For US and Canadian merchants

---

# Support

### Where can merchants find answers to common questions?

Visit our [merchant help center](https://help.business.afterpay.com/hc/en-us) or contact your Cash App Afterpay account representative.

#### Quick links

* [Payment schedules and transaction fees](https://help.business.afterpay.com/hc/en-us/sections/6464826951705-Payment-Schedule-Transaction-Fees)
* [Refunds](https://help.business.afterpay.com/hc/en-us/sections/6464909479577-Refunds)
* [Order management](https://help.business.afterpay.com/hc/en-us/sections/6464856665113-Order-Management-Transaction-Description)

### How can a customer contact Cash App Afterpay support?

Customer support queries should be directed to [help.afterpay.com](https://help.afterpay.com/hc/en-us).

### Where can I check Cash App Afterpay's systems status?

You can view the current status of Cash App Afterpay at [https://status.afterpay.com](https://status.afterpay.com). Subscribe to receive status updates by email.

### Why is Google Analytics incorrectly attributing the referrer to Afterpay?

When customers pay with Cash App Afterpay, they are redirected to portal.afterpay.com pages during the checkout flow, before returning to your review or confirmation page. This results in Google Analytics seeing portal.afterpay.com as the last domain visited. Therefore, it attributes the referral to `portal.afterpay.com`.

To ensure that Google correctly identifies the real referral source, add `portal.afterpay.com` to your referral exclusion list.

For details on how to add Cash App Afterpay to your exclusion list see [Google's documentation.](https://support.google.com/analytics/answer/10327750?hl=en)

<Warning>
  Use <code>portal.afterpay.com</code> <strong>not</strong> <code>afterpay.com</code> or you'll hide all of the traffic originating from the Cash App Afterpay Shop Directory.
</Warning>

---

# Business Hub

The Cash App Afterpay Business Hub is where you manage your merchant account. It's a centralized workspace where you can view settlements, handle disputes, manage your team, and more. For more information about using Business Hub, see the Cash App Afterpay [Help Center](https://help.business.afterpay.com/hc/en-us).

You can log in to the Business Hub here:

[https://hub.us.afterpay.com/us](https://hub.us.afterpay.com/us)

<Info title="Trouble logging in?">
  If you have trouble logging in, try clearing your browser's session cookies and then try again.

  Click [here](https://hub.us.afterpay.com/forgot-password) to reset your password.
</Info>

## Credentials

As a Hub Admin (Business Hub administrator), you have secure access to your merchant credentials within the Business Hub.

Go to the Settings tab to find all the necessary information. Your direct link to the Settings tab is: [https://hub.us.afterpay.com/settings](https://hub.us.afterpay.com/settings).

Without Hub Admin permissions, you can still view the Merchant ID field.

## New user accounts

### Production

You can request for a user to be added to your Business Hub by contacting our [Merchant Admin team](https://help.afterpay.com/hc/en-au/requests/new?ticket_form_id=193406) with the following details:

* User's first name
* User's last name
* User's email address
* Level of access

For **Sandbox Business Hub** access - contact your delivery manager or Cash App Afterpay account manager.

## Role access

There are three standard user access types:

* Hub Admin

* User

* Read Only

The various access rights are described in the tables below.

**Cash App Afterpay Business Hub**

| Permissions                                         | Hub Admin | User | Read Only |
| --------------------------------------------------- | --------- | ---- | --------- |
| Access to tax invoices                              | Yes       | Yes  | Yes       |
| Access to settlement info                           | Yes       | Yes  | Yes       |
| Process refunds                                     | Yes       | Yes  | No        |
| View orders                                         | Yes       | Yes  | Yes       |
| Edit orders                                         | Yes       | Yes  | No        |
| View shop directory                                 | Yes       | Yes  | Yes       |
| View and edit shop directory                        | Yes       | Yes  | No        |
| View and edit team members                          | Yes       | Yes  | No        |
| View banking                                        | Yes       | No   | No        |
| View and edit banking                               | Yes       | No   | No        |
| View Afterpay IQ                                    | Yes       | Yes  | Yes       |
| View and edit custom access types                   | Yes       | No   | No        |
| View activity logs                                  | Yes       | No   | No        |
| View disputes                                       | Yes       | Yes  | Yes       |
| Manage disputes                                     | Yes       | No   | No        |
| Manage Cash App Afterpay products                   | Yes       | No   | No        |
| View account settings                               | Yes       | Yes  | Yes       |
| Manage account settings and sensitive business data | Yes       | No   | No        |

**In the Merchant Portal**

| Permissions                       | Hub Admin | User | Read Only |
| --------------------------------- | --------- | ---- | --------- |
| View and download tax invoices    | Yes       | Yes  | Yes       |
| View and download settlement info | Yes       | Yes  | Yes       |
| View order                        | Yes       | Yes  | Yes       |
| Edit orders                       | Yes       | Yes  | No        |
| Process refunds                   | Yes       | Yes  | No        |
| Edit shipped status               | Yes       | Yes  | No        |

## Business Hub activation email

When user accounts are created you receive an activation email.

* The activation email contains a link that is active for 45 minutes.

* You can use [Forgot My Password](https://hub.us.afterpay.com/forgot-password) if the link is no longer active.

### Activation link expired? Didn’t receive the activation email?

* Activation and ‘Forgot my Password’ emails are sent from [donotreply@afterpay.com](mailto:donotreply@afterpay.com)

* Please check your Junk or Spam mailbox

* Try adding [donotreply@afterpay.com](mailto:donotreply@afterpay.com) to your safe senders list

---

# Settlement reports

Settlement Reports explain in detail all payments made by Cash App Afterpay to you and help you to reconcile your accounts. There is one settlement report for each settlement to your bank account. Typically, there is one settlement every day that you capture a Cash App Afterpay order.

## View and download settlement reports

You can view and export your settlement files in the reconciliation tab of the [Business Hub](https://hub.us.afterpay.com/us).

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Viewing Settlement Reports-3.png" alt="Viewing Settlement Reports.png" noZoom />

You can export your settlement files using the Settlement Export option For additional download options, such as API requests, contact your account manager.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Downloading the Settlement Report-3.png" alt="Downloading the Settlement Report.png" noZoom />

## Download tax invoices

You can also download monthly invoices for tax reporting purposes. To download a tax invoice, select **Tax invoice** button in the reconciliation tab. Configure the details of your settlement report and click **Download**.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Tax Invoices - Modal-2.png" alt="Tax Invoices - Modal.png" noZoom />

## Settlement report fields

| Description           | Type   | Format            | Example Value    | Displayed in CSV Format                              |
| --------------------- | ------ | ----------------- | ---------------- | ---------------------------------------------------- |
| Settlement Date       | String | See table below   | See table below  | See table below                                      |
| Order Date and Time   | String | dd/MM/yyyy HH:mm  | 12/01/2018 10:43 | "24/06/2019 22:56"                                   |
| Order Month           | String | MMM               | Jan              | "Jun"                                                |
| Order Year            | String |                   | 2019             | "2019"                                               |
| Afterpay Order ID     | Number | 79043810          | 12345679         | "79169085"                                           |
| Merchant Order ID     | String | Merchant Supplied | 2345678          | "2345678"                                            |
| Merchant Refund ID    | String | Merchant Supplied | 9163251003631241 | "9163251003631241"                                   |
| Order Amount          | String | $00.00 or $0.00   | \$85.95          | "85.95" - with the currency symbol before the number |
| Settlement Amount     | String | $00.00 or $0.00   | \$85.95          | "85.95" - with the currency symbol before the number |
| Merchant Fee excl Tax | String | $00.00 or $0.00   | \$5.46           | "5.46" - with the currency symbol before the number  |
| Merchant Fee Tax      | String | $00.00 or $0.00   | \$0.55           | "0.55" - with the currency symbol before the number  |
| Merchant Fee incl Tax | String | $00.00 or $0.00   | \$6.00           | "6.00" - with the currency symbol before the number  |
| Net Settlement Amount | String | $00.00 or $0.00   | \$79.95          | "79.95" - with the currency symbol before the number |
| Type                  | String |                   | Order            | "Order"                                              |
| Channel               | String |                   | Online           | "Online"                                             |
| Store Name            | String |                   |                  |                                                      |
| Store Id              |        |                   |                  | 9756                                                 |
| Device Name           |        |                   |                  | "POS251"                                             |
| Device Id             |        |                   |                  | 38301                                                |
| Afterpay Refund ID    | Number |                   |                  | 4561545                                              |
| Refund Date and Time  | String | dd/MM/yyyy HH:mm  |                  | "24/06/2019 18:43"                                   |
| Acquirer Terminal ID  |        |                   |                  |                                                      |
| Consumer Country      | String |                   |                  | "US"                                                 |

---

# Migrate from Afterpay to Cash App Afterpay

<Warning title="Important">
  If your app uses an explicit allowlist of Afterpay domains, you 

  *must*

   add 

  `api.cash.app`

   and 

  `cash.app`

   to the allowlist.
</Warning>

## API integration

There are no changes to the APIs, so you don't need to make any changes to your backend systems. While the terminology has changed, the API endpoints are the same.

## Afterpay Messaging

We currently support two messaging products, both of which work with Cash App Afterpay.

[On-Site Messaging](../AFTERPAY-MESSAGING/Getting-Started-with-Afterpay-On-Site-Messaging.md) is our current messaging product. Our previous product is messaging from the [JavaScript Library](../AFTERPAY-MESSAGING/JavaScript-Library.md).

**On-Site Messaging**

If you use On-Site Messaging, it will be updated automatically, with advance notice sent via email.

If you use elements of Afterpay Messaging, then see the [Getting Started with Afterpay On-Site Messaging](../AFTERPAY-MESSAGING/Getting-Started-with-Afterpay-On-Site-Messaging.md) page for more information.

**JavaScript Library**

If you use the JavaScript Library for your messaging, it will be updated automatically, with advance notice sent via email.

<Note>
  If you use a specific version of the script, update to version 

  `1.x.js`

  .
</Note>

## Differences between Afterpay and Cash App Afterpay

* Cash App Afterpay is only available in the USA. Australia, New Zealand, and Canada use the Afterpay brand. The United Kingdom uses the Clearpay brand.

* Cash App Afterpay operates in US dollars only. [Cross Border Trade](../WELCOME/caa-cross-border-trade.md) is available.

* US customers will see *Cash App Afterpay* on your product and payment pages instead of *Afterpay*.

## Brand Assets

See the [Brand Assets](../MARKETING/Brand-Assets.md) page in this guide for new assets.

See the [Cash App Afterpay Merchant guidelines](https://www.figma.com/deck/yC8BbsBfhxkSnxrw8VtYna/Cash-App-Afterpay-%E2%80%93-Merch\[…]kF1jqQt-1\&scaling=min-zoom\&content-scaling=fixed\&page-id=0%3A1) online presentation for detailed information on how to display Cash App Afterpay.

Custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, view our [FAQ](faq-migration.md) page.

---

# Platforms

This section is for merchants who use a platform for their integration. Find your platform in the list below for information on migration from Afterpay to Cash App Afterpay.

* [Adobe Commerce (Magento 2)](adobe-commerce-migration.md)

* [Adyen](adyen-migration.md)

* [Big Commerce](big-commerce-migration.md)

* [Ecwid](ecwid-migration.md)

* [PrestaShop](prestashop-migration.md)

* [Salesforce Commerce Cloud](salesforce-cc-migration.md)

* [Shopify](shopify-migration.md)

* [Stripe](stripe-migration.md)

* [Wix](wix-migration.md)

* [WooCommerce](woocommerce-migration.md)

<Info title="Don't see your platform?">
  Some platforms can't host Cash App Afterpay because these platforms are not available in the United States. Other platforms are not be available for Cash App Afterpay yet, but will be in the future. Contact us for more information.
</Info>

---

# Adobe Commerce Migration

To use the Cash App Afterpay product with Adobe Commerce (Magento 2), upgrade your extension to the latest version. Specifically:

* Minimum v5.4.2 for Magento 2.4

* Minimum v4.3.3 for Magento 2.3

* Minimum v1.2.4 for Adobe PWA (Progressive Web Application) Studio

If you are on a lower version than these, please update. See the [Update My Adobe Commerce Extension](#update-my-adobe-commerce-extension) section below if you are not sure how to upgrade your extension to the latest version.

If you are on minimum or higher version, existing settings and configurations continue to work as before; there is no need to change them.

See the [Adobe Commerce Getting Started](/cash-app-afterpay/guides/platforms/adobe-commerce-magento) page for detailed technical information on the Cash App Afterpay integration with Adobe Commerce.

***

## Update My Adobe Commerce Extension

***

The Cash App Afterpay extension update method depends on how you, the merchant, have originally installed the Afterpay module.

If you used [Composer](https://getcomposer.org/) to install the Afterpay module, then use Composer to update it. If you used a manual process to install theAfterpay module, then use a [manual update](#manual-update) to update it.

The extension update process depends on whether you want to use [Composer](https://getcomposer.org/) to make the update, or do a [manual update](#manual-update). We recommend that you [update with Composer](#update-with-composer).

In either case, backup your system files before you start an update.

<Note>
  The module used to update to Cash App Afterpay is still called Afterpay. This doesn't affect any of the instructions or advice below.
</Note>

### Update with Composer

<Note>
  In the instructions below, the 

  `[ADOBE-COMMERCE]`

   folder refers to the root folder where Adobe Commerce/Magento is installed.
</Note>

1. Open the Command Line Interface (CLI) and go to the `[ADOBE-COMMERCE]` folder on your server.

2. Run one of the following commands in the table to update the Afterpay module, depending on the Magento version:

| Magento version | Command to run                                      |
| --------------- | --------------------------------------------------- |
| 2.4             | composer require afterpay-global/module-afterpay:^5 |
| 2.3             | composer require afterpay-global/module-afterpay:^4 |
| \< 2.3.0        | composer require afterpay-global/module-afterpay:^4 |

3. Make sure that Composer finishes the installation without errors.

4. Run the Adobe Commerce setup upgrade: `php bin/magento setup:upgrade`.

5. Run the Adobe Commerce Dependencies Injection Compile: `php bin/magento setup:di:compile`.

6. Run the Adobe Commerce Static Content deployment: `php bin/magento setup:static-content:deploy`.

7. Run the Adobe Commerce System Cache Flush: `php bin/magento cache:flush`.

### Cash App Pay Update with Composer

This section only applies if you have Cash App Pay installed together with Afterpay.

<Note>
  In the instructions below, the 

  `[CASH-APP-PAY]`

   folder refers to the root folder where Cash App Pay is installed.
</Note>

1. Open the Command Line Interface (CLI) and go to the `[CASH-APP-PAY]` folder on your server.

2. Run one of the following commands in the table to update the Cash App Pay module, depending on the Magento version:

| Magento version | Command to run                                      |
| --------------- | --------------------------------------------------- |
| 2.4             | composer require afterpay-global/module-afterpay:^5 |
| 2.3             | composer require afterpay-global/module-afterpay:^4 |
| \< 2.3.0        | composer require afterpay-global/module-afterpay:^4 |

Then:

3. Make sure that Composer finishes the installation without errors.

4. Run the Adobe Commerce setup upgrade: `php bin/magento setup:upgrade`.

5. Run the Adobe Commerce Dependencies Injection Compile: `php bin/magento setup:di:compile`.

6. Run the Adobe Commerce Static Content deployment: `php bin/magento setup:static-content:deploy`.

7. Run the Adobe Commerce System Cache Flush: `php bin/magento cache:flush`.

## Manual Update

This method does not use Composer. It is more complex than using Composer, but just as effective when done correctly. Follow the instructions below.

### Remove old Afterpay files/folders

<Note>
  In the instructions below, the 

  `[ADOBE-COMMERCE]`

   folder refers to the root folder where Adobe Commerce/Magento is installed.
</Note>

1. Remove all the files in: `[ADOBE-COMMERCE]/app/code/Afterpay/Afterpay`. Then you are ready to download the Afterpay Extension.

### Download the Afterpay Extension

The extension is on GitHub. Do the following:

1. Go to GitHub for the link to [Magento 2](https://github.com/afterpay/afterpay-magento-2). The source code needed depends on your version of Magento. For these details, see the [Readme file](https://github.com/afterpay/afterpay-magento-2#readme).

2. Under the green *Code* heading, click **Download ZIP**. See the screenshot below:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/adobe-comm-manual-install.png" alt="adobe-comm-manual-install.png" noZoom />

3. Unzip your files and put them into a temporary folder.

<Info title="Install Folder">
  You can install Adobe Commerce in any folder on your server. In this guide, `[ADOBE-COMMERCE]` is the name of the root folder where Adobe Commerce is installed.
</Info>

#### Run the Commands

1. Copy the files from your temporary folder to the `[ADOBE-COMMERCE]/app/code/Afterpay/Afterpay` folder. The temporary folder is the one you created in Step 3 in the *Download the Afterpay Extension* section above.

2. Open the Command Line Interface (CLI) and make sure you are the owner of the `[ADOBE-COMMERCE]` folder. Run all CLI commands as the owner of the folder, not `root` and without `sudo`.

3. From the CLI, run the commands below:

| Command                                          | Description                                    |
| :----------------------------------------------- | :--------------------------------------------- |
| php bin/magento module:enable Afterpay\_Afterpay | Enable Afterpay extension.                     |
| php bin/magento setup:upgrade                    | Adobe Commerce setup upgrade.                  |
| php bin/magento setup:di:compile                 | Adobe Commerce dependencies injection compile. |
| php bin/magento setup:static-content:deploy      | Adobe Commerce static content deployment.      |
| php bin/magento cache:flush                      | Adobe Commerce system cache flush.             |

Now you need to repeat the process for the *Cash App Pay Extension for Magento 2*:

1. Remove the existing files in the `[ADOBE-COMMERCE]/app/code/Afterpay/CashApp` folder.

2. Download and copy the files to the `[ADOBE-COMMERCE]/app/code/Afterpay/CashApp` folder. The source code path is based on the Magento version [here](https://github.com/afterpay/cash-app-pay-magento-2).

3. Open the Command Line Interface (CLI) and run the commands below:

| Command                                         | Description                                    |
| :---------------------------------------------- | :--------------------------------------------- |
| php bin/magento module:enable Afterpay\_CashApp | Enable the Cash App Pay extension.             |
| php bin/magento setup:upgrade                   | Adobe Commerce setup upgrade.                  |
| php bin/magento setup:di:compile                | Adobe Commerce dependencies injection compile. |
| php bin/magento setup:static-content:deploy     | Adobe Commerce static content deployment.      |
| php bin/magento cache:flush                     | Adobe Commerce system cache flush.             |

You can find a table of the Afterpay Plugins for Adobe Commerce/Magento 2 [here](https://github.com/afterpay/afterpay-magento-2#install-manually). It also contains useful information on the manual installation process.

## Brand Assets

There are some new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# Adyen Migration

Please contact your commercial contact at Adyen, or reach out to [support@adyen.com](mailto:support@adyen.com), to understand if and how this impacts your integration.

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# BigCommerce Migration

Contact [Merchant Support](/cash-app-afterpay/guides/welcome/getting-started/support) for information on migrating from Afterpay to Cash App Afterpay on a BigCommerce platform.

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

<Note>
  BigCommerce merchants with Afterpay Site Messaging will notice a discrepancy in the branding after the automatic migration from Afterpay to Cash App Afterpay.

  As expected, Cash App Afterpay branding will appear on your product display pages/cart and during the Cash App Afterpay checkout flow. But the payment method display on your website's checkout page will still show the former Afterpay branding.

  This is a temporary situation that we do not expect to last more than a few months.
</Note>

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# Ecwid Migration

Contact [Merchant Support](/cash-app-afterpay/guides/welcome/getting-started/support) for information on migrating from Afterpay to Cash App Afterpay on an Ecwid platform.

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes to assets:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# PrestaShop Migration

To migrate from Afterpay to Cash App Afterpay, update your module. When you upgrade the Afterpay module, you automatically receive the user experience benefits of Cash App Afterpay.

See the instructions below:

## Migrating to the New Cash App Afterpay Branding

There are two ways to migrate from Afterpay to Cash App Afterpay:

* [Use the PrestaShop Marketplace](#use-the-prestashop-marketplace)

* [Use the Module Manager updating tool](#use-the-module-manager-updating-tool)

<Note>
  We strongly recommend that you always use the latest version of the Afterpay module.
</Note>

## Use the PrestaShop Marketplace

When the latest version of the Afterpay module is released on the PrestaShop Marketplace, the PrestaShop store should detect the new version. The PrestaShop store automatically shows the upgrade option.

To upgrade, to the following:

1. Go to the *Module Manager* section on the left menu bar. See the picture below:

   ![prestashop-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-1.png)

2. Use the search bar to find the Afterpay installed module and click **Upgrade available**. See the picture below:

   ![prestashop-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-2.png)

3. A confirmation window appears, see the picture below:

   ![prestashop-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-3.png)

4. Ensure you have a backup of the site before any upgrade. Click **Go to maintenance page** to avoid possible cache issues. Click **Upgrade Anyway** if you have a backup of the site and are confident you can problem solve if necessary.

When the upgrade is finished you receive a confirmation message. The **Actions** button shows the regular options.

<Note>Open the Afterpay configuration *Settings* section to check that all the configurations are correct after the upgrade. See the picture below:</Note>
![prestashop-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-4.png)

## Use the Module Manager Updating Tool

This is a manual update procedure you can use if you have disabled the upgrade option on your store. Do the following:

1. Go to the Module Manager Admin panel.

2. Go to the Prestashop Addons Marketplace and download the upgrade you want. We strongly recommend that you always have the latest version of the code.

3. To [download the files](https://addons.prestashop.com/en/other-payment-methods/51381-afterpay-buy-now-pay-later-always-interest-free.html) you must be logged into your PrestaShop account.

4. Open the *Module Manager* section and click **Upload a module**. See the picture below:

   ![prestashop-5.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-5.png)

5. Select the previously downloaded file from your computer and upload it. See the pictures below:

   ![prestashop-6.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-6.png)

6. A confirmation message appears when the module is installed.

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# Salesforce Commerce Cloud Migration

To migrate from Afterpay to Cash App Afterpay, update your cartridge. When you upgrade the Afterpay cartridge, you automatically receive the user experience benefits of Cash App Afterpay.

* Update the cartridge to v24.1.3 or higher

See the instructions below:

1. To use the Cash App Afterpay product with Salesforce, download the latest version of the Afterpay cartridge [here](https://github.com/afterpay/afterpay-salesforce-commerce-cloud).

2. See the [Install the Cartridge and Import the Metadata](#install-the-cartridge-and-import-the-metadata) section below to install the new cartridge and integrate it with your systems.

<Note>
  The SFCC cartridge and the Business Manager call Cash App Afterpay by the single word Afterpay. This doesn't affect any of the instructions or advice below.
</Note>

## Install the Cartridge and Import the Metadata

To install the lastest version of the cartridge, do the following:

1. Download the cartridge

   * The current version of the cartridge is available directly from [Cash App Afterpay](https://github.com/afterpay/afterpay-salesforce-commerce-cloud)
   * It’s also hosted on Salesforce’s [AppExchange platform](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000R8GgbEAF\&tab=e)

2. Build the client-side Resources. These are the client-side CSS (Cascading Style Sheets) and JS (JavaScript) files that are specific to Cash App Afterpay; this is a required step.

   * Confirm that `package.json` contains the correct reference to the location of the SFRA base cartridge (Only for SFRA):

3. Set the path. Set the path to the base cartridge of SFCC which is required for the Cash App Afterpay cartridge to work.

   ```
   "paths": {
   "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
   },
   ```

4. Install/Run commands. These commands install the node in our cartridge onto your local storage and compiles the JS and CSS files residing in our cartridge.

   ```
   $ npm install
   $ npm run compile:js
   $ npm run compile:scss
   ```

5. Import the cartridge. Use **UX Studio** to import the cartridge. Alternatively, you can also use **Node Package Manager (npm)** and run **uploadCartridge**, or the **VSCode Prophet** plugin.

Once you have completed the five steps above, you are ready to import the metadata. See the section below.

### Import the Metadata

For the Cash App Afterpay integration to work, the following object structures (metadata) must be imported and configured in the **Business Manager**. Do the following:

1. In the cartridge bundle go to the folder *metadata/afterpay-meta-import/sites*.

2. Rename the *RefArch* folder to the ID of your site. You can find the site ID in *Administration* > *Sites* > *Manage Sites* in the *Business Manager*.

3. Compress the  *afterpay-meta-import* folder to generate the `afterpay-meta-import.zip` file.

4. In the *Business Manager*, go to *Administration* > *Site Development* > *Site Import & Export* and import the zipped file.

Once you have imported the metadata, you are ready to make some final checks. See the section below.

### Check For File Conflicts/Changes.

1. If you are using *SiteGenesis*, see the [SiteGenesis code changes](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/site-genesis-code-changes) page to add Cash App Afterpay-specific code changes to your base store cartridges.

2. If you are using *SFRA*, see the [SFRA Files change review](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/sfra-files-change-review) page to see the files that override the files in the base cartridge.

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# Shopify Migration

If you'realready using the **Afterpay US (New)** payment app, no action is required. The new Cash App Afterpay branding will be updated automatically. Here's how it should appear:

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-Afterpay-updated-method.png" />

If you haven't migrated from the **Afterpay (New)** payment app to **Afterpay US (New)**, see [Migrate to the Afterpay US App](#migrate-to-the-afterpay-us-app) below.

<Info>
  While the Shopify App Store listing and app logo will reflect the new Cash App Afterpay brand, the payment app itself will continue to be called 

  **Afterpay US**

  . If you see Afterpay US (New) under your additional payment methods, you're all set.
</Info>

## Afterpay US Messaging

Messaging automatically works if you use the Afterpay On-Site Messaging app or the liquid code snippet from the Afterpay technical guide. No work is needed, as the messaging is automatically enabled.

Messaging uses settings from Afterpay Messaging. It automatically displays the correct branding per region.

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

Any custom messaging updates must be reviewed by your Account Manager.

### Cash App Afterpay Messaging

Messaging automatically works if you use the Afterpay On-Site Messaging app, or the liquid code snippet from the Afterpay technical guide. No migration work is needed as the messaging is automatically enabled. Monitor your email for advance notice of this automatic update. The messaging uses settings from Afterpay Messaging and automatically displays the correct branding per region.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## Migrate to the Afterpay US app

<iframe src="https://player.vimeo.com/video/1051911198?badge=0&controls=0&autopause=0&player_id=0&app_id=58479" width="100%" height="360" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen title="Shopify Afterpay US Migration Video" />

If you haven't migrated to the Afterpay US app yet, follow these two steps:

1. Install the **Afterpay US** payment app.
2. Deactivate the **Afterpay** payment app you'd previously been using.

<Note>
  Before you start, make sure you meet the requirements for the migration, see 

  [Requirements](#requirements)

   at the bottom of the page.
</Note>

### Install the Afterpay US App

<Note>
  For this migration, you don't need your merchant credentials to configure Afterpay US.
</Note>

1. Click [here](https://accounts.shopify.com/store-login?redirect=settings%2Fpayments/alternative-providers/84934657) to download the Afterpay US payment app.
2. When the **Install app** screen appears, click **Install**. <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-AfterpayUS-install.png" />
3. Once installed, Afterpay US (New) appears in your list of apps, ready to activate. Click **Activate**.

Once Afterpay US (New) appears with the green 'Active' sign next to it, your customers can immediately use Afterpay US to make payments. You don't need to do any further work to configure the app.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-AfterpayUS-activated.png" />

### Deactivate the previous Afterpay app

The final task is to deactivate the **Afterpay (New)** payment app in Shopify. Despite its name, this is the app you'd previously been using.

1. Go to **Shopify Admin**.

2. Go to **Settings**, then select **Payments**.

3. Under Additional payment methods, select **Afterpay (New)**. Make sure *not* to select **Afterpay US (New)**, which you just installed. <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-AfterpayUS-delete-method.png" />

4. On the Afterpay (New) screen, click **Deactivate**, then click **Deactivate** again to confirm your choice.

5. Return to your list of additional payment methods. Make sure that **Afterpay US (New)** is listed as an active payment method; **Afterpay (New)** shouldn't be on the list. <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-Afterpay-updated-method.png" />

<Note>
  In case you need to issue a refund, capture payments, or void payments that were previously made with Afterpay, we recommend that you keep the 

  **Afterpay (New)**

   payment app in your system. After you deactivate the app, don't uninstall it.
</Note>

## New payment method name

The Afterpay US payment app uses a new payment method name: **Afterpay US (New)**.

If your store has post-order processes that rely on the payment method name—like Shopify Flows or custom reporting—update any references from **Afterpay (New)** to **Afterpay US (New)**.

This only applies to merchants with custom backend systems that use the payment method name to trigger workflows.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page or below for Shopify-specific FAQs.

#### Refunds - I’m having trouble completing a refund, what should I do?

If the payment was taken on the Afterpay payment gateway and you have uninstalled the app, you must reinstall the app. Follow [these instructions](/cash-app-afterpay/guides/platforms/shopify) to install the Afterpay app. You will not need to configure your Afterpay app again.

Please do not activate the Afterpay app (leave it deactivated).

#### Cross Border Trade (CBT) - are all customers available to use Cross Border Trade on my Shopify store?

Cross Border Trade is available to Afterpay customers. It is not yet available to Cash App customers new to Afterpay.

Before the customer checks out, they see the appropriate brand for your shop's region. When the customer checks out, they see the appropriate brand based on the region associated with their Afterpay account.

For example, if your store is set in US, and your customer is based in the Canada, they will see the following brands:

* On your Shopify store: Cash App Afterpay

* During Afterpay checkout: Afterpay

#### Help! I accidentally uninstalled the Afterpay (New) app.

If you uninstalled the Afterpay (New) payment app when migrating to the Afterpay US app, you must reinstall Afterpay (New) to manage outstanding Afterpay orders placed before the migration.

Follow these steps:

1. Use this link to log in to your Shopify account and reinstall the app: [Reinstall Afterpay (New) App](https://accounts.shopify.com/store-login?redirect=settings%2Fpayments/alternative-providers/1057655)

2. Once you reinstall the app, don't activate it. Reinstalling without activating lets you manage transactions that occurred before you migrated.

3. Now that the app is reinstalled, you can issue refunds for pre-migration Afterpay orders, capture payments for pending transactions, and void payments as needed.

<Info title="Keep the app installed!">
  To avoid any issues with managing pre-migration Afterpay orders, we recommend keeping the Afterpay (New) app installed on your Shopify store.
</Info>

#### Afterpay appears twice at checkout

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-Afterpay-appears-twice.png" />

If Afterpay appears twice at checkout (as shown above), make sure to deactivate the **Afterpay (New)** app. Only the **Afterpay US (New)** app should be active. Follow the instructions to [deactivate the previous Afterpay app](#deactivate-the-previous-afterpay-app).

#### Update the Afterpay Banner

If you use the banner as part of your messaging, follow the instructions below to update it:

1. On Shopify, open the code editor to edit the theme files.

2. In theme.liquid, delete `{% section 'afterpay-banner' %}`.

3. Delete the afterpay-banner.liquid file.

4. Follow the steps [here](/cash-app-afterpay/guides/platforms/shopify/add-a-cash-app-afterpay-banner-to-shopify) to add the Cash App Afterpay banner to your theme.

#### Requirements

To avoid issues installing the new Afterpay US payment app, check that you have Shopify installed and working.

Make sure that your company or organization meets the following requirements:

Your business address is in one of the the following:

* Australia
* Canada
* Hong Kong SAR
* New Zealand
* United Kingdom
* United States

You must ship to the United States.

You must accept the currency USD (United States Dollars).

---

# Stripe Migration

Please follow the instructions provided by Stripe [here](https://support.stripe.com/questions/afterpay-is-now-branded-as-cash-app-afterpay-in-the-us).

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# Wix Migration

No action is needed. The brand updates automatically appear when the migration from Afterpay to Cash App Afterpay occurs. See the [FAQ](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) for when this migration will occur.

<Note>
  *Cash App Afterpay*

   may appear as 

  *Afterpay*

   on the administration page of the Wix website.
</Note>

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# WooCommerce Migration

To use the Cash App Afterpay product with WooCommerce, update the *Afterpay Gateway for WooCommerce* extension to the latest version, minimum v3.8.7

If you are on a lower version than this, please update. See the [Update Plugin](#update-plugin) section below if you're not sure how to upgrade your plugin to the latest version.

If you are on the minimum or higher version, existing settings and configurations continue to work as before; there is no need to change them.

## Update Plugin

To update the 'Afterpay Gateway for WooCommerce' plugin, please follow the below steps.

<Note>The Cash App Afterpay plugin is called the Afterpay Gateway for WooCommerce. This doesn't affect any of the instructions or advice below.</Note>
As updates for the **Afterpay Gateway for WooCommerce** plugin are released, notifications appear in WordPress Admin.

A number appears in WordPress Admin next to the Plugins link, it shows the number of plugin updates available.

![wc-update-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-1.png)

<Note>
  We strongly recommend that you backup website files and data before you do an update.
</Note>

### Upgrade Instructions

1. Go to the **WordPress Admin Dashboard**.

2. Go to **Plugins** > **Installed Plugins**.

3. Find the **Afterpay Gateway for WooCommerce** in the plugin list.

   > The version update notification is displayed, with links to the release details, and to update the plugin.

4. Click the **update now** link.

   ![wc-update-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-2.png)

5. The **Afterpay Gateway for WooCommerce** plugin now starts to update.

   ![wc-update-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-3.png)

6. Once complete, the notification bar turns green and the text changes to **Updated!**.

   ![wc-update-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-4.png)

## Brand Assets

There are new Cash App Afterpay brand assets to use at checkout and across your site. See the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) page in this guide for these new assets.

The table below has examples of the changes:

|         | Afterpay                                                | Cash App Afterpay                                       |
| ------- | ------------------------------------------------------- | ------------------------------------------------------- |
| Logos   | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-logo-resized.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-white-logo-resized.png" /> |
| Buttons | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-button.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-button.png" /> |

Any custom messaging updates must be reviewed by your Account Manager.

## Messaging

Messaging is automatically updated if you use On-Site Messaging, our current messaging product, or its predecessor that used the JavaScript library for messaging. In both cases wait for the automatic update process to occur. Monitor your email for advance notice of this automatic update.

See the table below for an example of the changes:

| Afterpay                                                | Cash App Afterpay                                       |
| ------------------------------------------------------- | ------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ap-mess-2.png" /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/caap-mess-1.png" /> |

The automatic Messaging update includes changes to *learn more*/lightbox asset if you use that.

If you use elements of Afterpay Messaging but not the standard Onsite Messaging Widget, then update the Afterpay elements with new Cash App Afterpay elements. See the [Brand Assets](#brand-assets) section above.

Any custom messaging updates must be reviewed by your Account Manager.

## FAQs

If you have a technical question on the migration, see our [FAQs for the Migration](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/migration-fa-qs) page.

---

# SDK Migration Guide

<Info>This guide is relevant for merchants using the [iOS](https://github.com/afterpay/sdk-ios) and [Android](https://github.com/afterpay/sdk-android) native app SDKs for their current Afterpay integration.</Info>
All merchant-owned surfaces featuring “Afterpay” will need to be updated to reflect the new “Cash App Afterpay” brand. This includes the product detail page, cart, checkout, FAQs, emails, and any other pages using Afterpay branding.

## What do I need to do?

### Afterpay checkout

No action is needed. The brand updates will automatically appear within Afterpay checkout when Afterpay is migrated to Cash App Afterpay.

### UI messaging elements

The native Afterpay SDK provides its own UI elements that merchants can use ([iOS](https://afterpay.github.io/sdk-ios/ui-components/) and [Android](https://afterpay.github.io/sdk-android/ui-components/)). These UI elements are embedded in the app's codebase and can't be controlled dynamically from Cash App Afterpay's backend.

The steps to migrate from Afterpay branding to Cash App Afterpay branding depends on whether you use Afterpay's UI elements or your own custom UI elements.

#### Afterpay UI elements

If you use Afterpay UI elements, update your SDK to version 4.8+ on Android and version 5.8+ on iOS to access the rebranded assets.

When you update, you'll see new names that refer to both the Afterpay themes and the Cash App Afterpay themes.  A mapping of the themes and their assets are in the table below.

| Legacy Afterpay theme | Afterpay asset                                          | New Cash App Afterpay theme | New Cash App Afterpay asset                             |
| --------------------- | ------------------------------------------------------- | --------------------------- | ------------------------------------------------------- |
| mintOnBlack           | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Button_Checkout.png" /> | Default                     | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashAppAfterpay_Button_Checkout.png" /> |
| blackOnMint           | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Button_Continue.png" /> | Alt                         | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashAppAfterpay_Button_Continue (1).png" /> |
| blackOnWhite          | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Button_Buy.png" /> | Light Monochrome            | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashAppAfterpay_Button_Buy (1).png" /> |
| whiteOnBlack          | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Button_Pay.png" /> | Dark Monochrome             | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashAppAfterpay_Button_Pay.png" /> |

##### Cash App Afterpay regions

If your region migrated to the new Cash App Afterpay themes, then the SDK will use the new Cash App Afterpay assets. You must select your preferred theme.

**Asset changes**

* The "Place order" button is replaced by a "Continue with" button. All other button types are the same.
* For the Price Breakdown component, the US region now only supports the Lockup logo type ([iOS](https://afterpay.github.io/sdk-ios/ui-components/price-breakdown/#logo-type) and [Android](https://afterpay.github.io/sdk-android/ui-components/price-breakdown/#logo-type)). Both the Compact Badge and Badge logo types are no longer supported in the US region.

##### Afterpay regions

If your region uses the Afterpay themes, you'll still need to select the appropriate Cash App Afterpay theme that corresponds to the Afterpay asset. However, there will be no changes to the UI and all logos will remain supported.

#### Custom UI elements

If you use custom UI elements, update your custom assets with our rebranded versions [here](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets).

### Need help?

If you have any questions, please contact your Account Manager.

---

# FAQs for the Migration

<Warning title="Important">
  If your app uses an explicit allowlist of Afterpay domains, you 

  *must*

   add 

  `api.cash.app`

   and 

  `cash.app`

   to the allowlist.
</Warning>

## Migration Requirements

<AccordionGroup>
  <Accordion title="Why is Afterpay changing its checkout experience?">
    Afterpay is becoming more easily accessible to Cash App users as part of Afterpay's integration with Cash App.

    This means we're changing the Afterpay logo where it appears on your site to attract the 50M Cash App users\* who do not use Afterpay while retaining your current Afterpay shoppers.

    The new Afterpay assets for your site incorporate proven messaging and design to acquire Cash App users and continue transacting with Afterpay users.

    Merchants who update Afterpay throughout their site will benefit from incremental sales and new customers from our total network.

    *\* Definitions & Source: A Cash App active is defined as a monthly transacting active user with at least one transaction monthly. Actives eligible for Afterpay include account owners who are 18+ and non-business accounts as of 2024.*
  </Accordion>

  <Accordion title="Is this change related to Cash App for Business?">
    No. Cash App for Business is a product that enables small, often single proprietor businesses to set up a business profile  to accept Cash App payments.
  </Accordion>

  <Accordion title="Do I need a new Cash App Pay merchant account?">
    No. This update gives you access to Cash App customers through the existing Afterpay experience. You just need to update the brand - no other changes are needed.
  </Accordion>

  <Accordion title="Will my integration need to be recertified?">
    Merchants with existing integrations will receive seamless updates, and Afterpay will complete all certifications before updates are made. We expect merchants will have minimal or no involvement with these changes, depending on how merchants displayed Afterpay.
  </Accordion>

  <Accordion title="Are my existing Afterpay customers automatically enrolled into the experience change?">
    The checkout experience will not change for the existing Afterpay customers. These customers will use the same login credentials, see the same checkout experience, and continue to service all orders via Afterpay.
  </Accordion>

  <Accordion title="Are updates to my &#x22;learn more&#x22; lightbox asset necessary? What do I need to update in order to remain in compliance?">
    Yes, we will make the necessary changes on your behalf if you use [Afterpay Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started). Please contact your Account Manager for specific questions.
  </Accordion>

  <Accordion title="I haven't been able to transact with Afterpay, as the Afterpay Messaging is no longer visible on my website. What can I do before I can take advantage of attracting new Cash App users?">
    Our Support Hub is available to help you take advantage of the new brand. Please view our Support Hub [here](https://help.business.afterpay.com/hc/en-us).
  </Accordion>

  <Accordion title="I'm interested in using Afterpay On-Site Messaging. Should I migrate to On-Site Messaging as part of this change?">
    Yes, we recommend coupling any site rebranding work with implementing Dynamic Messaging. Please speak to your Merchant Delivery partner for guidance.
  </Accordion>
</AccordionGroup>

## Customer Support Questions

Customers are the people that buy your goods or services. These are some questions they may ask.

<AccordionGroup>
  <Accordion title="As a customer, if I sign up for Cash App Afterpay do I get a Cash App account automatically?">
    No, customers won't automatically get a Cash App account when they sign up for Cash App Afterpay.
  </Accordion>

  <Accordion title="Can customers combine payments from their Cash App wallet and their Cash App Afterpay payment instrument (card)?">
    No. When you pay with Cash App, you can use your balance. If you do not have enough money then you can pay with a linked debit card instead.

    Cash App Afterpay customers' payment instruments (cards) are unchanged.
  </Accordion>

  <Accordion title="Is normal Cash App functionality still available such as paying with Bitcoin and buying shares?">
    Yes, this change does not change the way Cash App's customers use Cash App to send, bank, and invest.
  </Accordion>

  <Accordion title="Can teenagers with Cash App accounts use Cash App Afterpay?">
    No, Cash App Afterpay is only available to customers over the age of 18.
  </Accordion>

  <Accordion title="What is the customer experience before placing an order (UX flows)?">
    There are three key touchpoints to show your customers:

    * Product details

    * Shopping cart

    * Checkout pages

    See our [Cash App Afterpay Merchant Guidelines](https://www.figma.com/deck/yC8BbsBfhxkSnxrw8VtYna/Cash-App-Afterpay-%E2%80%93-Merch\[…]kF1jqQt-1\&scaling=min-zoom\&content-scaling=fixed\&page-id=0%3A1) guidelines to learn about the customer experience.
  </Accordion>

  <Accordion title="What is the customer experience after placing an order (notifications, emails, servicing)?">
    See our [Cash App Afterpay Merchant Guidelines](https://www.figma.com/deck/yC8BbsBfhxkSnxrw8VtYna/Cash-App-Afterpay-%E2%80%93-Merch\[…]kF1jqQt-1\&scaling=min-zoom\&content-scaling=fixed\&page-id=0%3A1) guidelines to learn about the customer experience.
  </Accordion>

  <Accordion title="When are you informing your customer base of this change?">
    Throughout 2025, both Afterpay and Cash App will make this update clear to our combined 58M monthly transacting active customers. We will also launch scaled awareness campaigns to excite and attract even more customers for our merchants.
  </Accordion>
</AccordionGroup>

## Merchant Support Questions

This section has questions that merchants may ask.

<AccordionGroup>
  <Accordion title="I already have both Afterpay and Cash App Pay, how does this affect my integration?">
    Cash App Pay and Cash App Afterpay will remain two separate products and integrations. See the [What is Cash App Pay and What is Cash App Afterpay?](/cash-app-afterpay/guides/welcome/getting-started/cash-app-pay-vs-cash-app-afterpay) page for details about the two products.

    Cash App Pay is not affected by this change.

    If you currently use Afterpay, your branding changes to Cash App Afterpay. See the [Migrate from Afterpay to Cash App Afterpay](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay) page for specific information about your integration method and how to update your branding from Afterpay to Cash App Afterpay.
  </Accordion>

  <Accordion title="Can I still use the Afterpay Business Hub?">
    Yes. All orders are still being processed by Afterpay and will be reflected in the Business Hub.
  </Accordion>

  <Accordion title="I support Afterpay in other countries outside the US.  How will this change affect those regions?">
    The change is only applicable to the US (not inclusive of US territories). The experience will not change outside of the US, and the existing Afterpay brand will remain in place outside the US.
  </Accordion>

  <Accordion title="Will the Afterpay SDKs be updated with Cash App related assets?">
    Yes.
  </Accordion>

  <Accordion title="How do I access analytic data?">
    There is access to the same analytics that you have today. All Afterpay orders are captured and reported in Hub/Portal/IQ.
  </Accordion>

  <Accordion title="With the influx of new customers, do you expect a decline in Average Order Value (AOV)?">
    No, we do not expect a decline in AOV thanks to our proprietary data and underwriting.
  </Accordion>

  <Accordion title="Will there be an updated Cash eCommerce Implementation guide?">
    See our [Migration Guides](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay) for all integration details related to this update.
  </Accordion>

  <Accordion title="How can I find out about future Cash App Afterpay or Cash App changes or new features?">
    You'll receive emails about important updates on what is changing and when. Please make sure your contact information is up to date in your Merchant Hub.
  </Accordion>

  <Accordion title="How will this change affect my conversion rates?">
    We're making this change to serve the total customer network of Afterpay and Cash App. Today, 50 million *Cash App actives* do not use Afterpay. This change allows Afterpay's merchants to seamlessly transact with meaningfully more customers than ever before.

    This change has been thoroughly tested and proven to attract new Cash App users while also retaining existing Afterpay users.

    *\* Definitions & Source: A Cash App active is defined as a monthly transacting active user with at least one transaction monthly. Actives eligible for Afterpay include account owners who are 18+ and non-business accounts as of 2024.*
  </Accordion>

  <Accordion title="How will Cross Border Trade (CBT) work with Cash App Afterpay? For example, Clearpay to Cash App, Cash App to Cash App Afterpay or Cash App Afterpay to Cash App">
    Cash App Afterpay customers can still make CBT purchases. Cash App customers that are new to Cash App Afterpay will not see options to use CBT.
  </Accordion>

  <Accordion title="Are Disputes affected by this change?">
    No, there is no effect on disputes.
  </Accordion>

  <Accordion title="Is Express Checkout supported with Cash App Afterpay?">
    Yes. Express Checkout continues to work the same as before.
  </Accordion>

  <Accordion title="Will the Merchant Hub URL change?">
    No, the URL stays the same: [https://portal.afterpay.com/us/login-email](https://portal.afterpay.com/us/login-email)
  </Accordion>

  <Accordion title="I'm currently using OAuth with Afterpay - how will this affect my integration?">
    OAuth continues to work the same as before.
  </Accordion>

  <Accordion title="I support Afterpay in other countries outside the US.  How will this change affect those regions?">
    The change is only applicable to the US (not inclusive of US territories). The experience will not change outside of the US, and the existing Afterpay brand will remain in place outside the US.
  </Accordion>

  <Accordion title="Are there any changes to Afterpay's Monthly Payments availability?">
    No. Pay Monthly continues to be available to Cash App Afterpay customers.
  </Accordion>

  <Accordion title="I'm re-platforming my e-comm front end in the next quarter – what is Block's guidance?">
    We recommend moving to the new brand as soon as possible.
  </Accordion>

  <Accordion title="Are refunds affected by this change?">
    No, there is no effect on refunds.
  </Accordion>

  <Accordion title="Are settlements affected by this change?">
    No, there is no effect on settlements.
  </Accordion>

  <Accordion title="How will Cash App and Afterpay handle version releases/rollouts?">
    This depends on your integration method. See the documentation specific to your integration method to learn about the rollout.
  </Accordion>

  <Accordion title="Will merchants be able to differentiate which orders are from Cash App customers?">
    No, this is not possible today.
  </Accordion>

  <Accordion title="How do you know whether to direct the customer to Cash App or Afterpay if they haven't logged in yet?">
    We use the customer data provided during the Create Checkout API call.
  </Accordion>

  <Accordion title="Is there a hard cutover date?">
    We recommend making any changes needed by March 17, 2025.
  </Accordion>
</AccordionGroup>

---

# Brand Assets

There are links to a variety of visual assets on this page. Use them to inform your customers that Cash App Afterpay is available as a payment method.

To increase brand awareness, we recommend using brand assets with Cash green. See the [Cash App Afterpay Merchant guidelines](https://www.figma.com/deck/yC8BbsBfhxkSnxrw8VtYna/Cash-App-Afterpay-%E2%80%93-Merchant-Guidelines?node-id=1-61\&viewport=-67%2C-97%2C0.47\&t=oY1HyyBF6E1NB35m-1\&scaling=min-zoom\&content-scaling=fixed\&page-id=0%3A1) online presentation for much more information on how to display and present Cash App Afterpay.

<br />

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Showcase.png" alt="Payment Badge - Green.png" noZoom />

<br />

<br />

## Logos

<Info title="We strongly recommended going code-first.">
  Our embeddable code snippets are designed to optimize your checkout experience. For implementation best practices, see our 

  [Merchant Guidelines](https://www.figma.com/deck/yC8BbsBfhxkSnxrw8VtYna/Cash-App-Afterpay-%E2%80%93-Merchant-Guidelines?node-id=1-61&viewport=-67%2C-97%2C0.47&t=oY1HyyBF6E1NB35m-1&scaling=min-zoom&content-scaling=fixed&page-id=0%3A1)

  .
</Info>

### Logo Lockup

| Green Black                                                                                                                                  | Green White                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Lockup - Green Black.png" alt="Lockup - Green Black.png" noZoom />                                                | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Lockup - Green White.png" alt="Lockup - Green White.png" noZoom />                                               |
| `html <img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/new-color-black-32.svg" height="32" />` | `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/new-color-white-32.svg" height="32" />` |

<br />

| Black                                                                                                                                      | White                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Lockup - Black.png" alt="Lockup - Black.png" noZoom />                                                    | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Lockup - White.png" alt="Lockup - White.png" noZoom />                                                    |
| `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/new-mono-black-32.svg" height="32" />` | `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/new-mono-white-32.svg" height="32" />` |

### Payment Badge

#### Rounded

<table>
  <tr>
    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Green.png" alt="Payment Badge - Green.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/icon/color.svg" height="24" />`
    </td>

    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Green on dark.png" alt="Payment Badge - Green on Black.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/icon/color.svg" height="24" />`
    </td>
  </tr>
</table>

<table>
  <tr>
    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Monochrome Black on light.png" alt="Payment Badge - Mono Light.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpay.com/en-US/integration/logo/icon/mono-light.svg" height="24" />`
    </td>

    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Monochrome White on dark.png" alt="Payment Badge - Mono Dark.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpay.com/en-US/integration/logo/icon/mono-dark.svg" height="24" />`
    </td>
  </tr>
</table>

#### Squared

<table>
  <tr>
    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Sqaured - Green on light.png" alt="Payment Badge - Sqaured - Green on light.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/color.svg" height="24" />`
    </td>

    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Squared - Green on dark.png" alt="Payment Badge - Squared - Green on dark.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/color.svg" height="24" />`
    </td>
  </tr>
</table>

<table>
  <tr>
    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Squared - Monochrome Black on light.png" alt="Payment Badge - Squared - Monochrome Black on light.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/mono-light.svg" height="24" />`
    </td>

    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Payment Badge - Squared - Monochrome White on dark.png" alt="Payment Badge - Squared - Monochrome White on dark.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/mono-dark.svg" height="24" />`
    </td>
  </tr>
</table>

#### Alternative

<table>
  <tr>
    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/alternative-badge-on-light.png" alt="alternative-badge-on-light.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/alt-badge/color.svg" height="24" />`
    </td>

    <td>
      <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/alternative-badge-on-dark.png" alt="alternative-badge-on-dark.png" noZoom />

      ***

      `html<img alt="Cash App Afterpay" src="https://static.afterpaycdn.com/en-US/integration/logo/alt-badge/color.svg" height="24" />`
    </td>
  </tr>
</table>

## Afterpay Messaging

Afterpay Messaging informs your customers—as they browse—that pay by installments with Afterpay is available. This helps to improve your conversion rates and average order value.

Visit our [Messaging Guide](/cash-app-afterpay/guides/afterpay-messaging/getting-started) to learn about implementation.

<Tabs>
  <Tab title="xs">
    <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Messaging Lockup - 12px.png" alt="Messaging Lockup - 12px.png" noZoom />
  </Tab>

  <Tab title="sm">
    <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Messaging Lockup - 14px.png" alt="Messaging Lockup - 14px.png" noZoom />
  </Tab>

  <Tab title="md">
    <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Messaging Lockup - 16px.png" alt="Messaging Lockup - 16px.png" noZoom />
  </Tab>

  <Tab title="lg">
    <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Messaging Lockup - 18px.png" alt="Messaging Lockup - 18px.png" noZoom />
  </Tab>
</Tabs>

## Buttons

<Info title="We strongly recommended going code-first.">
  Our embeddable code snippets are designed to optimize your checkout experience. For implementation best practices, see our 

  [Merchant Guidelines](https://www.figma.com/deck/yC8BbsBfhxkSnxrw8VtYna/Cash-App-Afterpay-%E2%80%93-Merchant-Guidelines?node-id=1-61&viewport=-67%2C-97%2C0.47&t=oY1HyyBF6E1NB35m-1&scaling=min-zoom&content-scaling=fixed&page-id=0%3A1)

  .
</Info>

### Button Styles

#### Rectangular

| Black Green                                                                                                                                                                                                                                                                                                                                      | Green Black                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Black Green.png" alt="Button Style - Black Green.png" noZoom />                                                                                                                                                                                                                                              | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Green Black.png" alt="Button Style - Green Black.png" noZoom />                                                                                                                                                                                                                                              |
| `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/color-on-black.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/black-on-green.svg" height="48" style="border: 0;" /></button>` |

<br />

| Black White                                                                                                                                                                                                                                                                                                                                      | White Black                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Black White.png" alt="Button Style - Black White.png" noZoom />                                                                                                                                                                                                                                              | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - White Black.png" alt="Button Style - White Black.png" noZoom />                                                                                                                                                                                                                                              |
| `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/white-on-black.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/black-on-white.svg" height="48" style="border: 0;" /></button>` |

#### Rounded

| Black Green                                                                                                                                                                                                                                                                                                                                              | Green Black                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Rounded Black Green.png" alt="Button Style - Rounded Black Green.png" noZoom />                                                                                                                                                                                                                                              | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Rounded Green Black.png" alt="Button Style - Rounded Green Black.png" noZoom />                                                                                                                                                                                                                                              |
| `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/color-on-black-rounded.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/black-on-green-rounded.svg" height="48" style="border: 0;" /></button>` |

<br />

| Black White                                                                                                                                                                                                                                                                                                                                              | White Black                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Rounded Black White.png" alt="Button Style - Rounded Black White.png" noZoom />                                                                                                                                                                                                                                              | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Style - Rounded White Black.png" alt="Button Style - Rounded White Black.png" noZoom />                                                                                                                                                                                                                                              |
| `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/white-on-black-rounded.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/afterpay/black-on-white-rounded.svg" height="48" style="border: 0;" /></button>` |

### Button Types

| Checkout With                                                                                                                                                                                                                                                                                                                                                                              | Continue With                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type  - Checkout with.png" alt="Button Type  - Checkout with.png" noZoom />                                                                                                                                                                                                                                                                                      | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type  - Continue with.png" alt="Button Type  - Continue with.png" noZoom />                                                                                                                                                                                                                                                                                      |
| `html<button aria-label="Checkout with Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Checkout with Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/checkout-with-afterpay/color-on-black.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Continue with Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Continue with Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/continue-with-afterpay/color-on-black.svg" height="48" style="border: 0;" /></button>` |

<br />

| Pay With                                                                                                                                                                                                                                                                                                                                                                    | Buy With                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type  - Pay with.png" alt="Button Type  - Pay with.png" noZoom />                                                                                                                                                                                                                                                                            | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type  - Buy with.png" alt="Button Type  - Buy with.png" noZoom />                                                                                                                                                                                                                                                                                    |
| `html<button aria-label="Pay with Cash App Afterpay" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Pay with Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/pay-with-afterpay/color-on-black.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Buy with Cash App Afterpay (Green)" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Buy with Cash App Afterpay" aria-hidden="true" src="https://static.afterpaycdn.com/en-US/integration/button/buy-with-afterpay/color-on-black.svg" height="48" style="border: 0;" /></button>` |

<br />

| Checkout With - Green                                                                                                                                                                                                                                                                                                                                                                           | Continue With - Green                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type - Green - Checkout with.png" alt="Button Type - Green - Checkout with.png" noZoom />                                                                                                                                                                                                                                                                                    | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type - Green - Continue with.png" alt="Button Type - Green - Continue with.png" noZoom />                                                                                                                                                                                                                                                                          |
| `html<button aria-label="Checkout with Cash App Afterpay (Green)" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Checkout with Cash App Afterpay" aria-hidden="true" src="https://static.afterpay.com/en-US/integration/button/checkout-with-afterpay/black-on-green.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Buy with Cash App Afterpay (Green)" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Buy with Cash App Afterpay" aria-hidden="true" src="https://static.afterpay.com/en-US/integration/button/continue-with-afterpay/black-on-green.svg" height="48" style="border: 0;" /></button>` |

<br />

| Pay With - Green                                                                                                                                                                                                                                                                                                                                                                 | Buy With - Green                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type - Green - Pay with.png" alt="Button Type - Green - Pay with.png" noZoom />                                                                                                                                                                                                                                                                          | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Type - Green - Buy with.png" alt="Button Type - Green - Buy with.png" noZoom />                                                                                                                                                                                                                                                                          |
| `html<button aria-label="Pay with Cash App Afterpay (Green)" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Pay with Cash App Afterpay" aria-hidden="true" src="https://static.afterpay.com/en-US/integration/button/pay-with-afterpay/black-on-green.svg" height="48" style="border: 0;" /></button>` | `html<button aria-label="Buy with Cash App Afterpay (Green)" style="display: inline-block; vertical-align: middle; cursor: pointer; border: transparent; background: none;"><img alt="Buy with Cash App Afterpay" aria-hidden="true" src="https://static.afterpay.com/en-US/integration/button/buy-with-afterpay/black-on-green.svg" height="48" style="border: 0;" /></button>` |

## Marketing Assets

Coming soon!

## Download

**We strongly recommended going code-first.** Our embeddable code snippets are designed to optimize your checkout experience.

To download our brand assets, [click here](https://static.afterpaycdn.com/en-US/integration/\$ap-brand-assets.zip).

---

# On-Site Messaging Migration

Your existing Afterpay messaging will automatically map to the new Cash App Afterpay branding. The themes will transition automatically based on your current selections. All existing integration code will continue to work; no action is required unless you want to change themes.

These changes only apply to merchants in the US.

<Info>
  Background color detection afffects some asset themes. If background color dependency is marked "Yes," it means you'll see a light variant on a light background, and a dark variant on a dark background.
</Info>

### Messaging assets mapping

<Info>
  Badge configurations also apply to the compact badge
</Info>

| Asset Type             | Configuration                                         | Afterpay Theme       | Before                                                                       | Cash App Afterpay Theme               | After                                                                                                                                                        | Background Color Dependency |
| ---------------------- | ----------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| Default Lockup         | `"logoType": "lockup"`                                | Black lockup         | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Logo_Black.png" class="img-bg-light" /> | Mono light                            | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black_Monochrome.png" class="img-bg-light" />                                                                                 | No                          |
| Lockup - Mint          | `"logoType": "lockup", "lockupTheme": "mint"`         | Mint lockup          | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Logo_Mint.png" />                      | Color - Light variant OR Dark variant | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black.png" class="img-bg-light" /> or <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White (1).png" class="img-bg-light" /> | Yes                         |
| Lockup - White         | `"logoType": "lockup", "lockupTheme": "white"`        | White lockup         | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Logo_White.png" />                      | Mono dark                             | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White_Monochrome (1).png" />                                                                                                      | No                          |
| Lockup - Black         | `"logoType": "lockup", "lockupTheme": "black"`        | Black lockup         | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Logo_Black.png" class="img-bg-light" /> | Mono light                            | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black_Monochrome.png" class="img-bg-light" />                                                                                 | No                          |
| Badge Default          | `"logoType": "badge"`                                 | Black on mint badge  | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Badge_BlackonMint.jpg" />                      | Color - Light variant OR Dark variant | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black.png" class="img-bg-light" /> or <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White (1).png" class="img-bg-light" /> | Yes                         |
| Badge - Black on Mint  | `"logoType": "badge", "badgeTheme": "black-on-mint"`  | Black on mint badge  | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Badge_BlackonMint.jpg" />                      | Color - Light variant OR Dark variant | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black.png" class="img-bg-light" /> or <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White (1).png" class="img-bg-light" /> | Yes                         |
| Badge - Mint on Black  | `"logoType": "badge", "badgeTheme": "mint-on-black"`  | Mint on black badge  | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Badge_MintonBlack.png" />                      | Color - Light variant OR Dark variant | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black.png" class="img-bg-light" /> or <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White (1).png" class="img-bg-light" /> | Yes                         |
| Badge - White on Black | `"logoType": "badge", "badgeTheme": "white-on-black"` | White on black badge | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Badge_WhiteonBlack.png" />                      | Mono - Dark variant OR Light variant  | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black_Monochrome.png" class="img-bg-light" /> or <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White_Monochrome (1).png" class="img-bg-light" /> | Yes                         |
| Badge - Black on White | `"logoType": "badge", "badgeTheme": "black-on-white"` | Black on white badge | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Badge_BlackonWhite.png" />                      | Mono - Dark variant OR Light variant  | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_Black_Monochrome.png" class="img-bg-light" /> or <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/RGB_CashAppAfterpay_Logo_White_Monochrome (1).png" class="img-bg-light" /> | Yes                         |

### Modal assets mapping

| Asset Type  | Configuration           | Afterpay Modal | Before                                                  | Cash App Afterpay Modal          | After                                                   | Background Color Dependency |
| ----------- | ----------------------- | -------------- | ------------------------------------------------------- | -------------------------------- | ------------------------------------------------------- | --------------------------- |
| Mint Modal  | `"modalTheme": "mint"`  | Mint Modal     | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Mint_Modal.png" /> | Standard Cash App Afterpay Modal | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashAppAfterpay_Modal.png" /> | No                          |
| White Modal | `"modalTheme": "white"` | White Modal    | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_White_ Modal.png" /> | Standard Cash App Afterpay Modal | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashAppAfterpay_Modal.png" /> | No                          |

### Icon assets mapping

| Asset Type | Configuration         | Afterpay Icon | Before                                                  | Cash App Afterpay Icon | After                                                   | Background Color Dependency |
| ---------- | --------------------- | ------------- | ------------------------------------------------------- | ---------------------- | ------------------------------------------------------- | --------------------------- |
| Icon       | `"data-type": "icon"` | Afterpay Icon | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay_Icon.png" /> | Cash App Afterpay Icon | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/CashApp_PaymentBadge_Green.png" /> | No                          |

---

# Platforms - Quickstart

<Warning title="Important">
  If your app uses an explicit allowlist of Afterpay domains, you 

  *must*

   add 

  `api.cash.app`

   and 

  `cash.app`

   to the allowlist.
</Warning>

**How can I add Cash App Afterpay to my store?**

***

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay) for information on the migration from Afterpay to Cash App Afterpay.</Info>
Cash App Afterpay is integrated with many popular e-commerce platforms. Get up and running quickly, without having to write any code with our e-commerce plugins.

**Are You a Developer?**

If you are building a custom integration, see the [API Quickstart](/cash-app-afterpay/guides/api-development/api-quickstart) page for details.

## Step 1 - Choose Your platform

You need a platform that manages your payments. Cash App Afterpay is available on many of these platforms. Common platforms include Shopify, Magento and WooCommerce. If you don't find your platform you can still integrate with Cash App Afterpay. See the [API Quickstart](/cash-app-afterpay/guides/api-development/api-quickstart) page for details.

## Step 2 - Set Up Your Cash App Afterpay Merchant Account

Sign up for a merchant account at [get.afterpay.com](https://get.afterpay.com/app/).

## Step 3 - Connect Your Cash App Afterpay Account

Once your merchant account has been created, you can copy and paste your credentials into your platform plugin.

<Note>
  If you have a development environment you can connect your sandbox credentials to your plugin for testing.
</Note>

## Step 4 - Cash App Afterpay is Live!

Your customers can now use Cash App Afterpay at checkout. Join our shop directory so that we can send you highly qualified leads, and watch your sales grow!

---

# Adobe Commerce - Getting Started

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/adobe-commerce-magento-migration) for information on the migration from Afterpay to Cash App Afterpay.</Info>
To integrate Cash App Afterpay with Adobe Commerce, follow the instructions below.

**What are the requirements for the Cash App Afterpay Adobe Commerce Extension?**

***

<Info title="Supported Countries">
  Cash App Afterpay is available for **Adobe Commerce (Magento 2)** merchants with a store address in the United States only.
</Info>

[Express Checkout](../../../docs/EXPRESS-CHECKOUT/What-is-Express-Checkout.md) is available with Version 3.4.0 and above.

The Cash App Pay Extension for Adobe Commerce/Magento 2 is only available to US merchants. See the [Adobe Commerce - Install Extension](AC-Install-Extension.md) topic for more details.

### Adobe Commerce Version

The Cash App Afterpay Extension for Adobe Commerce (Magento) is compatible with version 2.2 or greater.

### Store Currency

The Cash App Afterpay Extension relies on a dedicated Website Scope used for each market region (country) with a corresponding Base Currency set in Adobe Commerce Admin.

To set the Base Currency, go to\
**Stores** → **Configuration** → **Currency Setup** and set the currency to:

* United States Dollars (USD)

## Next Step

Now install the extension; follow the instructions on the [Install Extension](AC-Install-Extension.md) page.

---

# Adobe Commerce - Install Extension

**How Can I Install and Enable the Adobe Commerce Extension?**

***

## Overview

There are two ways to install and enable the Adobe Commerce Cash App Afterpay Extension:

* Use [Composer](https://getcomposer.org) to automatically download and install the files it gets from [Packagist](https://packagist.org/). We recommend this method

* Do a manual install

Both these ways involve locating and installing the Cash App Afterpay Extension for Adobe Commerce (Magento 2). Composer does this task automatically. For manual installations, you must locate and download these public repos for Adobe Commerce (Magento 2):

* [Cash App Afterpay Extension for Magento 2](https://github.com/afterpay/afterpay-magento-2)

* [Cash App Pay Extension for Magento 2](https://github.com/afterpay/cash-app-pay-magento-2)

You can also use the "headless" methods, GraphQL and REST API. See the [Headless Support](#headless-support) section below.

## Composer

We recommend you use [Composer](https://getcomposer.org) to manage your repos and dependencies. This is a recommendation, not a requirement.

If you use Composer, make sure you install the correct module version that corresponds to your Adobe Commerce/Magento version. For example, module version 5.x works with Magento 2.4.x. The various modules and their corresponding Commerce/Magento version appear in this [GitHub table](https://github.com/afterpay/afterpay-magento-2#install-using-composer-recommended). See Step 2 below.

Do the following:

1. In Composer, open the Command Line Interface (CLI) and go to the *Adobe Commerce* project root directory on your server.

2. In the CLI, run this command to install the Cash App Afterpay module:  `composer require afterpay-global/module-afterpay`. See the [GitHub table](https://github.com/afterpay/afterpay-magento-2#install-using-composer-recommended) for the specific Cash App Afterpay module you need to specify.

3. Make sure that Composer finishes the installation without errors.

4. Run the Adobe Commerce setup upgrade: `php bin/magento setup:upgrade`.

5. Run the Adobe Commerce Dependencies Injection Compile: `php bin/magento setup:di:compile`.

6. Run the Adobe Commerce Static Content deployment: `php bin/magento setup:static-content:deploy`.

7. Run the Adobe Commerce System Cache Flush: `php bin/magento cache:flush`.

## Manual Procedure

This method does not use Composer. It is a more complex than using Composer, but just as effective when done correctly. Follow the instructions below.

### Download the Cash App Afterpay Extension

The extension is on the GitHub. Do the following:

1. Go to the GitHub for the link to [Magento 2](https://github.com/afterpay/afterpay-magento-2) for the most up-to-date version.

<Note>
  The Cash App Afterpay plugins and associated information are all in the [Afterpay-Magento-2](https://github.com/afterpay/afterpay-magento-2) part of the GitHub.
</Note>

The source code needed depends on your version of Magento. See the Readme file in the [Afterpay-Magento-2](https://github.com/afterpay/afterpay-magento-2) part of GitHub.

2. Under the green *Code* heading, click **HTTPS** and click **Download ZIP**. See screenshot below:

![adobe-comm-manual-install.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/adobe-comm-manual-install.png)

3. Unzip your files and put them into a temporary folder.

<Info title="Install Folder">
  You can install Adobe Commerce in any folder on your server. In this guide, \[ADOBE-COMMERCE] is the name of the root folder where Adobe Commerce is installed.
</Info>

## Run the Commands

1. Create the folder `Afterpay/Afterpay` in \[ADOBE-COMMERCE]/app/code.

2. Copy the files from your temporary folder to the `Afterpay/Afterpay` folder. The temporary folder is the one you created in Step 3 in the *Download the Afterpay Extension* section above.

3. Open the Command Line Interface (CLI) and make sure you are the owner of the \[ADOBE-COMMERCE] folder. Run all the CLI commands as the owner of the folder, not `root` and without `sudo`.

4. From the CLI, run the commands below:

| Command                                          | Description                                    |
| :----------------------------------------------- | :--------------------------------------------- |
| php bin/magento module:enable Afterpay\_Afterpay | Enable Afterpay extension.                     |
| php bin/magento setup:upgrade                    | Adobe Commerce setup upgrade.                  |
| php bin/magento setup:di:compile                 | Adobe Commerce dependencies injection compile. |
| php bin/magento setup:static-content:deploy      | Adobe Commerce static content deployment.      |
| php bin/magento cache:flush                      | Adobe Commerce system cache flush.             |

Now you need to repeat the process for the *Cash App Pay Extension for Magento 2*:

1. Create the folder `Afterpay/CashApp` in \[ADOBE-COMMERCE]/app/code.

2. Download and copy the files to the `Afterpay/CashApp` folder. The source code path is based on the Magento version [here](https://github.com/afterpay/cash-app-pay-magento-2).

3. Open the Command Line Interface (CLI) and run the commands below:

| Command                                         | Description                                    |
| :---------------------------------------------- | :--------------------------------------------- |
| php bin/magento module:enable Afterpay\_CashApp | Enable the Cash App Pay extension.             |
| php bin/magento setup:upgrade                   | Adobe Commerce setup upgrade.                  |
| php bin/magento setup:di:compile                | Adobe Commerce dependencies injection compile. |
| php bin/magento setup:static-content:deploy     | Adobe Commerce static content deployment.      |
| php bin/magento cache:flush                     | Adobe Commerce system cache flush.             |

You can find a table of the Afterpay Plugins for Adobe Commerce/Magento 2 [here](https://github.com/afterpay/afterpay-magento-2#install-manually). It also contains useful information on the manual installation process.

## Headless Support

You can also use [GraphQL](https://graphql.org/) or the [REST API](https://en.wikipedia.org/wiki/REST) to use Cash App Afterpay together with Adobe Commerce.

For details, see the following web pages on the GitHub:

* [Afterpay GraphQL Support page](https://github.com/afterpay/afterpay-magento-2/blob/main/Docs/GraphQL.md)

* [REST API page](https://github.com/afterpay/afterpay-magento-2/blob/main/Docs/RestAPI.md)

---

# Adobe Commerce - Configure Extension

*Basic Settings, Advanced Settings, Advanced Front End Settings and Express Checkout Settings.*

***

## Basic Settings

1. Login to Adobe Commerce Admin and go to  **Stores → Configuration → Sales → Payment Methods → Afterpay** (scroll down).

2. Click **Basic Settings**.

![acm2-a-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/acm2-a-small.png)

| Setting      | Value                                                                                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Enabled      | **Yes** - Cash App Afterpay switched on. <br />**No** - Cash App Afterpay disabled.<br /> Click the *Use Default* checkbox to use the default setting, which is Yes.                       |
| API Mode     | **Sandbox** - for development or staging environments. <br /> **Production** - for your live website.<br /> Click the *Use Default* checkbox to use the default setting, which is Sandbox. |
| Merchant ID  | Your Sandbox or Production Cash App Afterpay Merchant ID.                                                                                                                                  |
| Merchant Key | Your Sandbox or Production Cash App Afterpay Secret Key.                                                                                                                                   |

## Advanced Settings

1. Click **Advanced Settings**.

![acm-2-b-revised.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/acm-2-b-revised.png)

| Setting                  | Value                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| Minimum Order Total      | Shows the minimum price for an order payable with Cash App Afterpay.                                                          |
| Maximum Order Total      | Shows the maximum price for an order payable with Caash App Afterpay.                                                         |
| CBT Available Currencies | Lists the currencies available for [Cross Border Trade](/cash-app-afterpay/guides/welcome/getting-started/cross-border-trade) |

The above three settings are all read-only display fields. The information they display comes from the Cash App Afterpay API, so you cannot edit them here.

| Setting                              | Value                                                                                                                                                                                                                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public Id                            | A publishable API key used by Cash App Afterpay's Dynamic Messaging feature. It is a unique identifier for the merchant account.                                                                                                                                                                                    |
| Consumer Lending Enabled             | Shows if the merchant account is enabled for Pay Monthly (US merchants only). If you want Pay Monthly enabled and are a US merchant, contact Cash App Afterpay Sales.                                                                                                                                               |
| Consumer Lending Minimum Order Total | The minimum order total for the use of the customer lending facility.                                                                                                                                                                                                                                               |
| Update Merchant Configuration        | Click this button to update the limit configuration and specific countries from the Cash App Afterpay API.                                                                                                                                                                                                          |
| Debug                                | **Yes** - Debug logs are written to  "h-0": "/var/log/afterpay.log <br />**No** - Disabled. Click the *Use Default* checkbox to use the default setting, which is Yes.                                                                                                                                              |
| Display on Product Page              | **Yes** - Cash App Afterpay Displays on Product Page. Click the *Use Default* checkbox to use the default setting, which is Yes.                                                                                                                                                                                    |
| Display on Cart Page                 | **Yes** - Adobe Commerce Checkout - proceed to checkout page as normal.<br /> **Yes** - Express Checkout - enable Cash App Afterpay Express Checkout from cart page. <br />**No** - Cash App Afterpay will not display on the Cart page. Click the *Use Default* checkbox to use the default setting, which is Yes. |
| Sort Order                           | The order of payment methods at checkout.                                                                                                                                                                                                                                                                           |

![acm2-c-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/acm2-c-small.png)

| Setting               | Value                                                                                                                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Exclude Categories    | Select the relevant categories to exclude Cash App Afterpay from being available. Click the *Use Default* checkbox to use the default setting, which excludes nothing.                                                                                           |
| Payment Flow          | **Immediate Payment Flow** - Capture full payment. <br />**Deferred Payment Flow** - Capture incremental amounts as items are dispatched.                                                                                                                        |
| Enable Auto-Reversals | This is useful if an exception occurs when Adobe Commerce is finalising an order after Afterpay have approved the payment. In this case the payment is reversed automatically. This reversal helps prevent customers paying for orders that cannot be fulfilled. |

<Warning>
  In the table above, we do not recommend the use of the Auto-Reversals feature if you use an external Order Management System (OMS).
</Warning>

## Advanced Frontend Settings

Use these settings for custom-built themes on your website. The default of these settings is NO (disabled), which means your pages display in the default Adobe Commerce Luma theme, or similar.

These custom-built themes are not dependent on [Knockout.js](https://knockoutjs.com), which is the default frontend framework included with Adobe Commerce. If enabled, Advanced Frontend Settings allow Afterpay messaging to display on the product page, cart and mini-cart, regardless of the frontend framework used by your theme.

You, the merchant, must configure the Placement selectors and the Price selectors according to the theme you have designed and your web page type.

<Note>This feature is only available for Adobe Commerce 2.4 (and above) users.</Note>
Do the following:

1. Login to Adobe Commerce Admin and go to  **Stores → Configuration → Sales → Payment Methods → Afterpay** (scroll down).

2. Click **Advanced Frontend Settings**. The advanced frontend settings fields display, in the default setting of No, which means they are disabled. See screenshot below:

![Configuration-Settings-Stores-Magento-Admin.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Configuration-Settings-Stores-Magento-Admin.png)

The example screen below shows the range of settings when the advanced frontend settings fields are enabled:

![Hyva-Configuration-Settings-Stores-Magento-Admin.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Hyva-Configuration-Settings-Stores-Magento-Admin.png)

See the table below for information on the various settings.

<Note>
  In all cases, you should place Afterpay messaging immediately below the price element in the PDP (Product Page), cart and mini cart.
</Note>

| Setting                                  | Value                                                                                                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable for Product Page                  | Select **Yes** to enable Advanced Frontend Settings for product pages.                                                                                        |
| Placement selector (Product Page)        | Enter a CSS (Cascading Style Sheet) selector for a target element on the product page. Afterpay asset placement is injected below the first matching element. |
| Price selector (Product Page)            | Enter a CSS selector for the product price element. The product price is extracted from the first matching element.                                           |
| Placement selector (Bundle Product Page) | Enter a CSS selector for a target element on the bundle product page. Afterpay asset placement is injected below the first matching element.                  |
| Price selector (Bundle Product Page)     | Enter a CSS selector for the bundle product price element. The bundle product price is extracted from the first matching element.                             |
| Enable for Cart Page                     | Select **Yes** to enable Advanced Frontend Settings for the shopping cart page.                                                                               |
| Placement selector (Cart Page)           | Enter a CSS selector for a target element on the cart page. Afterpay asset placement is injected below the first matching element.                            |
| Price selector (Cart Page)               | Enter a CSS selector for the order price element. The order price is extracted from the first matching element.                                               |
| Enable for Mini Cart                     | Select **Yes** to enable Advanced Frontend Settings for the mini cart.                                                                                        |
| Placement selector (Mini Cart)           | Enter a CSS selector for a target element on the mini cart. Afterpay asset placement is injected below the first matching element.                            |
| Container selector (Mini Cart)           | Enter a CSS selector to select a container on the mini cart page. In the example above the container selector is #cart-drawer.                                |
| Price selector (Mini Cart)               | Enter a CSS selector for the mini cart order price element. The order price is extracted from the first matching element.                                     |

## Express Checkout Settings

1. Click **Express Checkout Settings**.

![express-checkout-settings-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/express-checkout-settings-small.png)

| Setting                 | Value                                                                                                                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display on Product Page | **Yes** - Can checkout directly from Product Page. <br />**No** - No checkout from the Product Page. Click the *Use Default* checkbox to use the default setting, which is Yes.  |
| Display on Cart Page    | **Yes** - Can checkout directly from Cart Page. <br />**No** - No checkout from the Cart Page. Click the *Use Default* checkbox to use the default setting, which is Yes.        |
| Display on Mini-Cart    | **Yes** - Can checkout directly from Mini-Cart. <br />**No** - No direct checkout from the Mini-Cart. Click the *Use Default* checkbox to use the default setting, which is Yes. |

---

# Adobe Commerce - Update Extension

**How can I update my Adobe Commerce Extension?**

***

The Cash App Afterpay extension update method depends on how you, the merchant, have originally installed the Cash App Afterpay module.

If you used [Composer](https://getcomposer.org/) to install the Cash App Afterpay module, then use Composer to update it. If you used a manual process to install the Cash App Afterpay module, then use a [manual update](#manual-update) to update it.

The Cash App Afterpay extension update process depends on whether you want to use [Composer](https://getcomposer.org/) to make the update, or do a [manual update](#manual-update). We recommend that you [update with Composer](#update-with-composer).

In either case, backup your system files before you start an update.

## Update with Composer

<Note>
  In the instructions below, the 

  `[ADOBE-COMMERCE]`

   folder refers to the root folder where Adobe Commerce/Magento is installed.
</Note>

1. Open the Command Line Interface (CLI) and go to the `[ADOBE-COMMERCE]` folder on your server.

2. Run one of the following commands in the table to update the Cash App Afterpay module, depending on the Magento version:

| Magento version | Command to run                                      |
| --------------- | --------------------------------------------------- |
| 2.4             | composer require afterpay-global/module-afterpay:^5 |
| 2.3             | composer require afterpay-global/module-afterpay:^4 |
| \< 2.3.0        | composer require afterpay-global/module-afterpay:^4 |

3. Make sure that Composer finishes the installation without errors.

4. Run the Adobe Commerce setup upgrade: `php bin/magento setup:upgrade`.

5. Run the Adobe Commerce Dependencies Injection Compile: `php bin/magento setup:di:compile`.

6. Run the Adobe Commerce Static Content deployment: `php bin/magento setup:static-content:deploy`.

7. Run the Adobe Commerce System Cache Flush: `php bin/magento cache:flush`.

### Cash App Pay Update with Composer

<Note>
  In the instructions below, the 

  `[CASH-APP-PAY]`

   folder refers to the root folder where Cash App Pay is installed.
</Note>

1. Open the Command Line Interface (CLI) and go to the `[CASH-APP-PAY]` folder on your server.

2. Run one of the following commands in the table to update Cash App Pay module, depending on the Magento version:

| Magento version | Command to run                                      |
| --------------- | --------------------------------------------------- |
| 2.4             | composer require afterpay-global/module-afterpay:^5 |
| 2.3             | composer require afterpay-global/module-afterpay:^4 |

3. Make sure that Composer finishes the installation without errors.

4. Run the Adobe Commerce setup upgrade: `php bin/magento setup:upgrade`.

5. Run the Adobe Commerce Dependencies Injection Compile: `php bin/magento setup:di:compile`.

6. Run the Adobe Commerce Static Content deployment: `php bin/magento setup:static-content:deploy`.

7. Run the Adobe Commerce System Cache Flush: `php bin/magento cache:flush`.

## Manual Update

This method does not use Composer. It is more complex than using Composer, but just as effective when done correctly. Follow the instructions below.

### Remove old Afterpay files/folders

<Note>
  In the instructions below, the 

  `[ADOBE-COMMERCE]`

   folder refers to the root folder where Adobe Commerce/Magento is installed.
</Note>

1. Remove all the files in: `[ADOBE-COMMERCE]/app/code/Afterpay/Afterpay`. Then you are ready to download the Cash App Afterpay Extension.

### Download the Cash App Afterpay Extension

The extension is on GitHub. Do the following:

1. Go to GitHub for the link to [Magento 2](https://github.com/afterpay/afterpay-magento-2). The source code needed depends on your version of Magento. For these details, see the [Readme file](https://github.com/afterpay/afterpay-magento-2#readme).

2. Under the green *Code* heading, click **Download ZIP**. See screenshot below:

![adobe-comm-manual-install.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/adobe-comm-manual-install.png)

3. Unzip your files and put them into a temporary folder.

<Info title="Install Folder">
  You can install Adobe Commerce in any folder on your server. In this guide, `[ADOBE-COMMERCE]` is the name of the root folder where Adobe Commerce is installed.
</Info>

### Run the Commands

1. Copy the files from your temporary folder to the `[ADOBE-COMMERCE]/app/code/Afterpay/Afterpay` folder. The temporary folder is the one you created in Step 3 in the *Download the Cash App Afterpay Extension* section above.

2. Open the Command Line Interface (CLI) and make sure you are the owner of the `[ADOBE-COMMERCE]` folder. Run all CLI commands as the owner of the folder, not `root` and without `sudo`.

3. From the CLI, run the commands below:

| Command                                          | Description                                    |
| :----------------------------------------------- | :--------------------------------------------- |
| php bin/magento module:enable Afterpay\_Afterpay | Enable Cash App Afterpay extension.            |
| php bin/magento setup:upgrade                    | Adobe Commerce setup upgrade.                  |
| php bin/magento setup:di:compile                 | Adobe Commerce dependencies injection compile. |
| php bin/magento setup:static-content:deploy      | Adobe Commerce static content deployment.      |
| php bin/magento cache:flush                      | Adobe Commerce system cache flush.             |

Now you need to repeat the process for the *Cash App Pay Extension for Magento 2*:

1. Remove the existing files in the `[ADOBE-COMMERCE]/app/code/Afterpay/CashApp` folder.

2. Download and copy the files to the `[ADOBE-COMMERCE]/app/code/Afterpay/CashApp` folder. The source code path is based on the Magento version [here](https://github.com/afterpay/cash-app-pay-magento-2).

3. Open the Command Line Interface (CLI) and run the commands below:

| Command                                         | Description                                    |
| :---------------------------------------------- | :--------------------------------------------- |
| php bin/magento module:enable Afterpay\_CashApp | Enable the Cash App Pay extension.             |
| php bin/magento setup:upgrade                   | Adobe Commerce setup upgrade.                  |
| php bin/magento setup:di:compile                | Adobe Commerce dependencies injection compile. |
| php bin/magento setup:static-content:deploy     | Adobe Commerce static content deployment.      |
| php bin/magento cache:flush                     | Adobe Commerce system cache flush.             |

You can find a table of the Cash App Afterpay Plugins for Adobe Commerce/Magento 2 [here](https://github.com/afterpay/afterpay-magento-2#install-manually). It also contains useful information on the manual installation process.

---

# Adyen

<Info title="Migrate from Afterpay to Cash App Afterpay">
  If you are an Afterpay merchant, see the 

  [Adyen Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/adyen-migration)

   for information on the migration from Afterpay to Cash App Afterpay.
</Info>

## Integration Process

To add Cash App Afterpay as a payment method, contact your Adyen Account Manager.

## Integration Documentation

[Learn how to accept Cash App Afterpay payments through Adyen](https://docs.adyen.com/payment-methods/afterpaytouch)

## Cash App Afterpay Messaging and Best Practice Guidelines

When you integrate to Cash App Afterpay through Adyen, see our [Cash App Afterpay Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started) pages to make the most of Cash App Afterpay on your site.

---

# Getting Started

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/big-commerce-migration) for information on the migration from Afterpay to Cash App Afterpay.</Info>
Follow the instructions below, starting with the Checkout Type.

### Checkout Type

The BigCommerce Checkout Type must be an *Optimized one-page checkout*.

To ensure the checkout type is correct:

1. Go to: *BigCommerce Control Panel> Advanced Settings > Checkout*.

2. Under *Checkout Settings*, the *Checkout Type* must be: *Optimized one-page checkout*. See picture below.

![bc-gs-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/bc-gs-1.png)

### Store Country

The Store Country must correspond to the Afterpay account region.

To ensure the store country is correct:

1. Go to: *BigCommerce Control Panel > Store Setup > Store Profile*.

2. Under *Contact Information*, the *Store Country* must be United States.

### Next Steps

* Next, you should [Add a Payment Option](BC-Add-Payment-Option.md).

* When you've done that, make sure your customers are aware of the Cash App Afterpay by adding some [Site Messaging](BC-Afterpay-Site-Messaging.md).

Finally to attract lots of new customers, join the Cash App Afterpay [Store Directory](../../MARKETING/Shop-Directory.md).

---

# Add Payment Option

## Configuration

Completing the below steps will enable and display Cash App Afterpay as a Payment Method. Do the following:

1. Go to *BigCommerce Control Panel*.

2. Go to *Settings* > *Payments*.

3. Under the *Online Payment Methods* section, click the drop-down arrow.

   ![add-payment-option-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/add-payment-option-1.png)

4. Locate *Afterpay* from the Online Payment Methods list and click **Set up**.

   ![add-payment-option-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/add-payment-option-2-2.png)

5. Enter the Merchant ID provided by Afterpay into the *Merchant ID* field.

6. Enter the Secret Key provided by Afterpay into the *Secret Key* field.

   ![add-payment-option-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/add-payment-option-3.png)

7. Additionally, you can configure the following settings:

   * **Transaction Type** — can be set to Authorize & Capture or Authorize Only. Authorize Only allows you to capture the funds manually. See [Manually Capturing Transactions (Authorize Only)](https://support.bigcommerce.com/s/article/Manually-Capturing-Transactions-Authorize-Only) to learn more.

   * **Test Mode** — set this to *Yes* to test checkout flow. Make sure this is set to *No* when your store goes live.

   <Note>
     You need Cash App Afterpay Sandbox Credentials to use Test Mode. Please contact your Afterpay Delivery Manager for assistance.
   </Note>

8. Click the **Save** button.

---

# Cash App Afterpay Site Messaging

**How can I add Cash App Afterpay Site Messaging to my product and cart pages?**

***

<Note>Be careful, as these instructions need you to edit code. Before you make any changes to theme template files, back up your current theme customizations.</Note>
There are two types of theme platform on BigCommerce; [Stencil](#stencil-theme) and [Blueprint](#blueprint-theme).

Follow the instructions below according to which theme platform your store uses.

If you are not sure what platform is used by your store, see [Which Theme Platform do I have?](https://support.bigcommerce.com/s/article/Which-Theme-Platform-do-I-have).

## Stencil Theme

1. Go to *Storefront* › *Script Manager*

2. Click **Create a Script**.

3. Set up the following:

   * **Name of Script:** Cash App Afterpay Messaging
   * **Description:** Place Cash App Afterpay Site Messaging on product and cart pages
   * **Location on page:** Footer
   * **Select pages where script will be added:** Store pages
   * **Script category:** Essential
   * **Script type:** Script
   * **Load method:** Default

4. Copy and paste the below script into Script Contents:

```javascript Stencil
<!-- Begin Afterpay Stencil Snippet for BigCommerce v3.1.2 -->
<script>
{{#or (if page_type '===' 'product') (if page_type '===' 'cart')}}
    (function(){
        const supported = ["AUD", "NZD", "USD"];
        const currency = '{{currency_selector.active_currency_code}}';
        if (supported.indexOf(currency) > -1) {
            {{#if page_type '===' 'product'}}
                let targetSelector = '.productView .productView-price';
            {{#if product.price.with_tax}}
                let priceSelector = '.productView-price .price--withTax';
                let cachedAmount = '{{product.price.with_tax.value}}';
            {{else}}
                let priceSelector = '.productView-price .price--withoutTax';
                let cachedAmount = '{{product.price.without_tax.value}}';
            {{/if}}
            {{else if page_type '===' 'cart'}}
                let targetSelector = 'ul.cart-totals li.cart-total:last-child';
                let priceSelector = '.cart-total-grandTotal';
                let cachedAmount = '{{cart.grand_total.value}}';
            {{/if}}
                const locales = {
                    AUD: 'en_AU',
                    NZD: 'en_NZ',
                    USD: 'en_US',
                };
                const init = function(){
                    Afterpay.createPlacements({
                        targetSelector: targetSelector,
                        attributes: {
                            locale: locales[currency],
                            currency: currency,
                            amount: cachedAmount,
                        }
                    });
                };
                const script = document.createElement('script');
                script.src = "https://js.afterpay.com/afterpay-1.x.js";
                script.dataset.min = "1.00";
                script.dataset.max = "2000.00";
                script.onload = function () {
                    init();
                    setInterval(() => {
                        if (cachedAmount != document.querySelector(priceSelector).innerText) {
                           cachedAmount = document.querySelector(priceSelector).innerText;
                           if (document.querySelector('afterpay-placement')) {
                               document.querySelector('afterpay-placement').dataset.amount = cachedAmount;
                           } else {
                               init();
                           }
                        }
                    }, 400);
                };
                document.head.appendChild(script);
        }
    })();
{{/or}}
</script>
<!-- End Afterpay Stencil Snippet for BigCommerce v3.1.2 -->
```

You can modify the script so that the banner will only display a price breakdown if the product meets your order minimum and maximum thresholds.

To do so, you will need to edit the following values within the script and set the minimum and maximum values to mirror your Cash App Afterpay account settings:

`script.dataset.min = "1.00";`\
`script.dataset.max = "800.00";`

<Note>
  Banner not showing up?

  Sometimes the script may not work because the HTML elements are named differently depending on your theme. Work with your developer to help update the script depending on your theme.
</Note>

## Blueprint Theme

1. Access your themes template files by going to *Storefront* › *Template Files*.

2. Find the file *Panels/ProductDetails.html*.

3. Copy the script below and paste it into the *Panels/ProductDetails.html* file:

```javascript Blueprint
<!-- Begin Afterpay Blueprint Snippet for BigCommerce v2.0.2 -->
<afterpay-placement></afterpay-placement>
<script>
    (function(){
        const supported = ["AUD", "NZD", "USD"];
        const currency = '%%GLOBAL_CurrentCurrencyCode%%';
        if (supported.indexOf(currency) > -1) {
            let priceSelector = '.ProductDetailsGrid .VariationProductPrice';
            let cachedAmount = '%%GLOBAL_RawProductPrice%%';
            const locales = {
                AUD: 'en_AU',
                NZD: 'en_NZ',
                USD: 'en_US',
            };
            const placement = document.querySelector('afterpay-placement');
            placement.dataset.locale = locales[currency];
            placement.dataset.currency = currency;
            placement.dataset.amount = cachedAmount;
            const script = document.createElement('script');
            script.src = "https://js.afterpay.com/afterpay-1.x.js";
            script.dataset.min = "1.00";
            script.dataset.max = "2000.00";
            script.onload = function () {
                setInterval(() => {
                    if (cachedAmount != document.querySelector(priceSelector).innerText) {
                       cachedAmount = document.querySelector(priceSelector).innerText;
                       placement.dataset.amount = cachedAmount;
                    }
                }, 400);
            };
            document.head.appendChild(script);
        }
    })();
</script>
<!-- End Afterpay Blueprint Snippet for BigCommerce v2.0.2 -->
```

You should now see Cash App Afterpay's messaging underneath the price of products and the cart total.

---

# Ecwid

<Info title="Migrate from Afterpay to Cash App Afterpay">
  If you are an Afterpay merchant, see the 

  [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/ecwid-migration)

   for information on the migration from Afterpay to Cash App Afterpay.
</Info>

## Configure Cash App Afterpay Payment

To enable Cash App Afterpay as a payment method and display the Cash App Afterpay assets on the product pages, do the following:

1. Log in to the *Ecwid Website Admin Portal*.

   ![ecwid-control-panel.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ecwid-control-panel.png)

2. Go to *Configuration* -> *Payment*.

   ![ecwid-navigate.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ecwid-navigate.png)

3. Contact Ecwid support [here](https://support.ecwid.com/hc/en-us/requests/new) to help with the Cash App Afterpay setup and installation. An alternative is to open the Ecwid *Control panel* and use *Open Live Chat* or email support.

4. Enter the Merchant ID and Secret Key supplied by Cash App Afterpay. Ensure *Test transactions (no real charges)* is set to **Disabled**.

   ![ecwid-mtid-secretkey.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ecwid-mtid-secretkey.png)

5. Double check that *Test transactions (no real charges)* is set to **Disabled**. See picture below:

   ![ecwid-check.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ecwid-check.png)

6. Update the *Appearance Options* text, insert the text: *Cash App Afterpay - Shop Now. Enjoy Now. Pay Later.*

   ![ecwid-text.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/ecwid-text.png)

7. Set *Enable this payment method at checkout* to **Enabled**.

   ![Enable payment method](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Ecwid_Control_Panel.png)

8. Click the **Save** button.

   ![Enable payment method](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Ecwid_Save.png)

Cash App Afterpay should now be installed and available for use by your customers. Cash App Afterpay should also appear on your product pages and as a payment option on the checkout page.

---

# Getting Started

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/presta-shop-migration) for information on the migration from Afterpay to Cash App Afterpay.</Info>
Follow the instructions below.

### Setting up Cash App Afterpay with PrestaShop

Cash App Afterpay has a module that you can install in the back office admin area for PrestaShop.

<Note>
  Before you begin you must:

  * Have a Cash App Afterpay merchant account to use the Cash App Afterpay module with PrestaShop. Click [here](https://get.afterpay.com) to sign up for a Cash App Afterpay merchant account.

  * Ensure that the Cash App Afterpay module for PrestaShop is compatible with PrestaShop versions 8, 1.7.x. and 1.6.x
</Note>

#### Install the Module

To install the module do the following:

1. In the *Modules* section of the PrestaShop admin area, select **Module Catalog**.

2. Enter `Afterpay` in the module search box.

3. Select **Install**.

4. Select **Configure**. The Afterpay configuration panel appears.

5. Enter your merchant ID and secret key and your API region and environment.

6. Click **Save** in the lower-right corner.

<Info>
  From time to time the Cash App Afterpay module is updated. To ensure you have the most up-to-date module, follow the procedure(s) in the [Updating the Cash App Afterpay Module](/cash-app-afterpay/guides/platforms/presta-shop/updating-the-cash-app-afterpay-module) page.
</Info>

| Setting                                    | Value                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Module is enabled                          | **Yes** - Cash App Afterpay turned on <br /> **No** - Cash App Afterpay disabled.                                                                                                                                                                                                                                                                                                                                    |
| Merchant ID                                | Your 9 digit Cash App Afterpay Merchant ID.                                                                                                                                                                                                                                                                                                                                                                          |
| Secret Key                                 | Your 128 character Cash App Afterpay secret key.                                                                                                                                                                                                                                                                                                                                                                     |
| API Environment                            | **Sandbox** - for testing. <br /> **Production** - For live order processing.                                                                                                                                                                                                                                                                                                                                        |
| Min Payment Limit/Max Payment Limit        | Current minimum and maximum Cash App Afterpay order thresholds. **These values are for information purposes and cannot be customized in Prestashop.**                                                                                                                                                                                                                                                                |
| Enable Multicurrency                       | Enable multicurrency support.                                                                                                                                                                                                                                                                                                                                                                                        |
| CBT Countries                              | [Cross Border Trade (CBT)](/cash-app-afterpay/guides/welcome/getting-started/cross-border-trade) allows you to sell internationally. Customers in foreign countries pay in their local currencies, while Afterpay continues to settle with you in your local currency. This information is supplied by Afterpay and cannot be edited. This value is for information purposes and cannot be customized in Prestashop. |
| Restricted Categories                      | This enables you to restrict Cash App Afterpay to selected product categories.                                                                                                                                                                                                                                                                                                                                       |
| Payment Info on Individual Product Page    | Enable to display Cash App Afterpay elements on individual product pages.                                                                                                                                                                                                                                                                                                                                            |
| Product Page HOOK                          | This property sets the HOOK where Cash App Afterpay messaging is linked to on the product page. Only change this value if the messaging doesn't appear correctly.                                                                                                                                                                                                                                                    |
| Price CSS (Cascading Style Sheet) Selector | This property sets the CSS selector needed to show the assets on the product page. Only change this value if it doesn't appear correctly.                                                                                                                                                                                                                                                                            |
| Product Page CSS Position Selector         | Cash App Afterpay messaging is moved after the CSS Selector DOM (Document Object Model) Element. Only change this value if it doesn't appear correctly.                                                                                                                                                                                                                                                              |
| Payment Info on Cart Page                  | Enable to display Cash App Afterpay elements on the cart page (available for PS 1.7 and higer).                                                                                                                                                                                                                                                                                                                      |
| Cart Page CSS Selector                     | This property set the CSS selector needed to show the assets on the cart page. Only change this value if it doesn't appear correctly.                                                                                                                                                                                                                                                                                |
| Canonical URLs                             | Only Enable this option if the checkout doesn't redirect correctly to the payment gateway and shows a 404 error.                                                                                                                                                                                                                                                                                                     |
| Debug mode                                 | Enable the debug logging. You can see these logs in the *Configure* > *Advanced Parameters* > *Logs* section.                                                                                                                                                                                                                                                                                                        |
| Enable Reversal                            | If Prestashop throws an exception while attempting to finalise an order after payment is approved by Cash App Afterpay, the payment can be reversed automatically. This may help to prevent scenarios where customers pay for orders that can't be fulfilled. Not recommended if an external Order Management System (OMS) is in use.                                                                                |

## Store currency and language

The module relies on a dedicated Website Scope being used for each market region (country) with a corresponding base currency and languages set in the PrestaShop admin area. As Cash App Afterpay is only available in the USA, set the market region to USA and the base currency to US dollars.

<Warning>
  Warning

  Check that your store's base currency is set to USD (\$).
</Warning>

To set the Base Currency:

1. Go to *International*.

2. Select the *Localization* page and use the *Default currency* option from the *Configuration* section.

For more information see this section of the [PrestaShop 1.7](http://doc.prestashop.com/display/PS17/Localization) & [PrestaShop 1.6](http://doc.prestashop.com/display/PS16/Understanding+Local+Settings) documentation.

## Testing your configuration

1. Go to a product page to check whether Cash App Afterpay appears as a payment option. If the Cash App Afterpay widget does not appear, check that you have entered your Cash App  Afterpay credentials correctly when you set up the Afterpay module.

2. If Cash App Afterpay appears correctly as a payment option, go to the checkout page to test that the Cash App Afterpay information displays correctly.

### Troubleshooting

If Cash App Afterpay does not update/display as expected, provide staff access to your PrestaShop admin panel for our Integration Support Team.

Send an email to [merchantadminus@afterpay.com](mailto:merchantadminus@afterpay.com) and include the:

* Admin panel URL

* Admin panel user

* Admin panel password

---

# Updating the Cash App Afterpay Module

Cash App Afterpay periodically updates its Cash App Afterpay module.

There are two ways to ensure your module is up-to-date:

* [Use the PrestaShop Marketplace](#use-the-prestashop-marketplace)

* [Use the Module Manager updating tool](#use-the-module-manager-updating-tool)

<Note>
  We strongly recommend that you always use the latest version of the Cash App Afterpay module.
</Note>

## Use the PrestaShop Marketplace

When a new version of the Cash App Afterpay module is released on the PrestaShop Marketplace, the PrestaShop store should detect the new version. The PrestaShop store automatically shows the upgrade option.

To upgrade, to the following:

1. Go to the *Module Manager* section on the left menu bar. See the picture below:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-1.png" alt="prestashop-1.png" noZoom />

2. Use the search bar to find the Afterpay installed module and click **Upgrade available**. See the picture below:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-2.png" alt="prestashop-2.png" noZoom />

3. A confirmation window appears, see the picture below:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-3.png" alt="prestashop-3.png" noZoom />

4. Ensure you have a backup of the site before any upgrade. Click **Go to maintenance page** to avoid possible cache issues. Click **Upgrade Anyway** if you have a backup of the site and are confident you can problem solve if necessary.

When the upgrade is finished you receive a confirmation message. The **Actions** button shows the regular options.

<Note>
  Open the Cash App Afterpay configuration 

  *Settings*

   section to check that all the configurations are correct after the upgrade. See the picture below:
</Note>

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-4.png" alt="prestashop-4.png" noZoom />

## Use the Module Manager Updating Tool

This is a manual update procedure you can use if you have disabled the upgrade option on your store. Do the following:

1. Go to the Module Manager Admin panel.

2. Go to the Prestashop Addons Marketplace and download the upgrade you want. We strongly recommend that you always have the latest version of the code.

3. To [download the files](https://addons.prestashop.com/en/other-payment-methods/51381-afterpay-buy-now-pay-later-always-interest-free.html) you must be logged into your PrestaShop account.

4. Open the *Module Manager* section and click **Upload a module**. See the picture below:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-5.png" alt="prestashop-5.png" noZoom />

5. Select the previously downloaded file from your computer and upload it. See the pictures below:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/prestashop-6.png" alt="prestashop-6.png" noZoom />

6. A confirmation message appears when the module is installed.

---

# Getting Started

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/salesforce-commerce-cloud-migration) for information on the migration from Afterpay to Cash App Afterpay.</Info>
Follow the instructions below:

Cash App Afterpay has cartridges that can be used with:

* Commerce Cloud's Storefront Reference Architecture (SFRA)

* A controller-based SiteGenesis

<Note>
  The cartridge supports SFRA versions 5 and 6.
</Note>

<Note>
  The cartridges can support both 

  [Direct Capture, and Auth and Capture Payment flows](../../API-DEVELOPMENT/API-Calls-and-Payment-Flows.md)

  . Contact your Cash App Afterpay Delivery Manager for instructions on implementing the Auth and Capture flow.
</Note>

## Features

Once you have Cash App Afterpay on your SFCC hosted website, the following features are present:

* Cash App Afterpay Messaging on Product, Cart and Category pages

* Cash App Afterpay as a Payment Method during checkout

* Cash App Afterpay Express Checkout

* During checkout Cash App Pay appears as a payment method alongside Cash App Afterpay

## Next Steps

Now install the cartridge; follow the instructions on the [Install Cartridge](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/install-cartridge-and-import-metadata) page.

After that you should:

1. [Configure the cartridge](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/configure-cartridge).

2. Make [SiteGenesis code changes](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/site-genesis-code-changes).

3. Do an [SFRA files change review](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/sfra-files-change-review).

4. Get plenty of new customers by joining the [Shop Directory](../../MARKETING/Shop-Directory.md)

---

# Install the Cartridge and Import the Metadata

<Note>The SFCC cartridge and the Business Manager call Cash App Afterpay by the single word Afterpay. This doesn't affect any of the instructions or advice below.</Note>
If you are a new merchant and do not have the Cash App Afterpay cartridge installed on your site, do the following:

1. Download the cartridge

   * The current version of the cartridge is available directly from [Cash App Afterpay](https://github.com/afterpay/afterpay-salesforce-commerce-cloud)
   * It’s also hosted on Salesforce’s [AppExchange platform](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000R8GgbEAF\&tab=e)

2. Build the client-side Resources. These are the client-side CSS (Cascading Style Sheets) and JS (JavaScript) files that are specific to Cash App Afterpay; this is a required step.

   * Confirm that `package.json` contains the correct reference to the location of the SFRA base cartridge (Only for SFRA):

3. Set the path. Set the path to the base cartridge of SFCC which is required for the Cash App Afterpay cartridge to work.

   ```
   "paths": {
   "base": "../storefront-reference-architecture/cartridges/app_storefront_base/"
   },
   ```

4. Install/Run commands. These commands install the node in our cartridge onto your local storage and compiles the JS and CSS files residing in our cartridge.

   ```
   $ npm install
   $ npm run compile:js
   $ npm run compile:scss
   ```

5. Import the cartridge. Use **UX Studio** to import the cartridge. Alternatively, you can also use **Node Package Manager (npm)** and run **uploadCartridge**, or the **VSCode Prophet** plugin.

Once you have completed the five steps above, you are ready to import the metadata. See the section below.

## Import the Metadata

For the Cash App Afterpay integration to work, the following object structures (metadata) must be imported and configured in the **Business Manager**. Do the following:

1. In the cartridge bundle go to the folder *metadata/afterpay-meta-import/sites*.

2. Rename the *RefArch* folder to the ID of your site. You can find the site ID in *Administration* > *Sites* > *Manage Sites* in the *Business Manager*.

3. Compress the  *afterpay-meta-import* folder to generate the `afterpay-meta-import.zip` file.

4. In the *Business Manager*, go to *Administration* > *Site Development* > *Site Import & Export* and import the zipped file.

Once you have imported the metadata, you are ready to make some final checks. See the section below.

## Check For File Conflicts/Changes.

1. If you are using *SiteGenesis*, see the [SiteGenesis code changes](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/site-genesis-code-changes) page to add Cash App Afterpay-specific code changes to your base store cartridges.

2. If you are using *SFRA*, see the [SFRA Files change review](/cash-app-afterpay/guides/platforms/salesforce-commerce-cloud/sfra-files-change-review) page to see the files that override the files in the base cartridge.

---

# SFCC Configure the Cartridge

## Set the Cartridge Path

Before the Cash App Afterpay functionality can be available to your site, there is a cartridge task. Your task is to add the cartridge names to the cartridge path of the site’s settings. To do this, do the following:

1. Log into *Business Manager*.

2. Go to *Administration*\* > *Sites* > *Manage Sites* > *\[yourSite]* > **Settings**.
   * If you are using SFRA (Salesforce Reference Architecture), enter: `int_afterpay_sfra:int_afterpay_core:app_storefront_base`. If you are using SFRA > 6.0.0 then you should use `int_afterpay_sfra_6 instead`.
   * If you are using SiteGenesis, enter: `int_afterpay_sg:int_afterpay_core` in front of SiteGenesis base cartridges.

3. Click **Apply**.

## Set SFCC (Demandware) Service

Go to *Administration* > *Operations* > *Services* > *Credentials* > and select the required service and enter the account details.

|          |                                                                                                                                                                                                |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL      | Sandbox [https://global-api-sandbox.afterpay.com/v2/](https://global-api-sandbox.afterpay.com/v2/) <br />Production [https://global-api.afterpay.com/v2/](https://global-api.afterpay.com/v2/) |
| User     | Enter the Merchant ID provided by Cash App Afterpay.                                                                                                                                           |
| Password | Enter the Secret Key provided by Cash App Afterpay.                                                                                                                                            |

## Set Cash App Afterpay Custom Site Preferences

<Note>The SFCC cartridge and the Business Manager call Cash App Afterpay by the single word Afterpay. This doesn't affect any of the instructions or description below.</Note>
To set the custom site preferences, do the following:

1. In *Business Manager*, go to the *Merchant Tools* > *Site Preferences* > *Custom Preferences*. A custom site preference group with the ID `Integration_Afterpay` is available for you to use. Select it and edit the attributes according to your Cash App Afterpay account data and the data shown in the table below.

<Note>
  Listed preferences are for the Afterpay cartridge v23.4.1 and above. If you are using any other versions see the integration guide in the documentation folder in the 

  [repository](https://github.com/afterpay/afterpay-salesforce-commerce-cloud)

  .
</Note>

| Site Preference                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Default                                                                                       |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Enable Afterpay (`enableAfterpay`)                                                     | Sets whether all of the cartridge functionality is active and visible on your storefront. You can use this field to temporarily disable the payment method at checkout along with all customer-facing messaging throughout the site without uninstalling the cartridge.                                                                                                                                                                                                                                                                       | No                                                                                            |
| Enable CashAppPay (`enableCashAppPay`)                                                 | Sets if Cash App Pay is enabled/disabled in the cartridge.<br />**Note:** Cash App Pay gives customers the option to pay with Cash App, but relies on a connection to your Cash App Afterpay merchant account for settlement. If you are setting this preference to `true`,  ensure that: <br />Cash App Pay integration is included in your Cash App Afterpay merchant contract and enabled on your Cash App Afterpay merchant account <br />Enable Cash App Afterpay is also true. Cash App Pay won’t load without it on the checkout page. | No                                                                                            |
| Brand settings (`apBrandSettings`)                                                     | Cash App Afterpay brand-related settings in JSON format where: <br />Brand – Afterpay <br />Service – the field is used to identify the service with Cash App Afterpay.(You can find the services under *Administration* > *Operations* > *Services*).                                                                                                                                                                                                                                                                                        | `{     "US": {         "brand": "afterpay",         "service": "afterpay.service.US"     } }` |
| Afterpay JavaScript URL (`apJavaScript`)                                               | The endpoint where the javascript library is obtained from – Use: <br />Sandbox - [https://js-sandbox.squarecdn.com/square-marketplace.js](https://js-sandbox.squarecdn.com/square-marketplace.js) <br />Production - [https://js.squarecdn.com/square-marketplace.js](https://js.squarecdn.com/square-marketplace.js)                                                                                                                                                                                                                        |                                                                                               |
| Afterpay Display Product Details Page Information (`apDisplayPdpInfo`)                 | Sets if the Cash App Afterpay messaging is displayed on the **Product Details** page.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Yes                                                                                           |
| Afterpay Display Product List Page Information (`apDisplayPlpInfo`)                    | Sets if the Cash App Afterpay messaging is displayed on the **Product List** Page.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | No                                                                                            |
| Afterpay Display Cart Page Information (`apDisplayCartInfo`)                           | Sets if the Cash App Afterpay messaging is displayed on the **Cart** Page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Yes                                                                                           |
| Afterpay Payment Mode (`apPaymentMode`)                                                | Sets if the payment should be authorized only or if the merchant will use **Direct Capture** instead.                                                                                                                                                                                                                                                                                                                                                                                                                                         | Merchant Specific – Select the ones to be supported.                                          |
| CapturePaymentTimeout (`apCaptureTimeout`)                                             | Sets timeout for the **Direct Timeout Capture** payments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                                                               |
| apDelayRetry (`apDelayRetry`)                                                          | Sets the delay time for the unavailable service                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                                                               |
| Enable Express Checkout (`apEnableExpressCheckout`)                                    | Enables the **Express Checkout** feature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Yes                                                                                           |
| Enable BuyNow (`apEnableExpressCheckoutBuyNow`)                                        | Enables the **BuyNow** mode. Skips review page on merchant checkout. (Note: Only used for **Integrated Shipping**)                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes                                                                                           |
| Express Checkout Shipping Strategy (`apExpressCheckoutShippingStrategy`)               | Select either **Integrated Shipping** (Cash App Afterpay Checkout prompts for shipping method), or **Deferred** (merchant site handles shipping method selection)<br /><br />**Note:** If there are multiple shipping methods in the cart, the cartridge disregards this preference and selects the deferred shipping strategy.                                                                                                                                                                                                               | Integrated                                                                                    |
| Description Express Checkout will use for In-Store Pickup (`apStorePickupDescription`) | Prompt to use in Cash App Afterpay Express Checkout for in-store pickup orders                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Available for next-day pickup                                                                 |
| Enable Express Checkout on Product Details Page (`apEnableExpressCheckoutPdp`)         | Enables Express Checkout directly from the product detail page. If this setting is disabled but Express Checkout is enabled, the button appears only on the cart page for SiteGenesis storefronts, the cart page and minicart for SFRA storefronts.                                                                                                                                                                                                                                                                                           | No                                                                                            |
| Enable Express Checkout option on cart (`apEnableExpressCheckoutCart`)                 | Enable Express Checkout option on cart and minicart(SFRA) page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                                                                                           |
| Default Controller Cartridge Name (`apControllerCartridgeName`)                        | This is used for SiteGenesis only and can be ignored for SFRA.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `app_storefront_controllers`                                                                  |
| Default Core Cartridge (`apCoreCartridge`)                                             | This is used for SiteGenesis only and can be ignored for SFRA.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `app_storefront_core `                                                                        |
| Restricted Products(`apRestrictedProducts`)                                            | The product ids of products that are to be excluded from Cash App Afterpay separated by “,”                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                                               |

## Add the Cash App Afterpay Image to the Payment Method (For SiteGenesis)

To display the Cash App Afterpay image on the site, you must add the image to your site:

1. Go to *Merchant Tools* > *Ordering* > *Payment Methods*.

2. Select the payment method with the ID *AFTERPAY/CASHAPPPAY* (depending on the target region) and locate the image attribute and upload the image included in the cartridge.

   The images are:

   * int\_afterpay\_sg/cartridge/static/default/images/logo-afterpay-colour.png

   * int\_afterpay\_sg/cartridge/static/default/images/cashapppay-logomark1x.png

---

# SiteGenesis Code Changes

To integrate the new Cash App Afterpay cartridge, you must modify your version of the SiteGenesis base cartridge files.

If you have made considerable changes to the SiteGenesis base cartridge files for your own store, consider using a merge tool. A three-way visual merge tool such as [Meld](https://meldmerge.org/) can be useful to make these changes.

<Note>
  If you use Salesforce Reference Architecture (SFRA), you can skip this page - there are no code changes needed.
</Note>

## Download file

Download the zip file [SiteGenesis Code Changes](https://cash-f.squarecdn.com/static/sitegenesis-code-changes-1.zip) for instructions to do the code changes.

---

# SFRA File Change Review

The following templates are present in Cash App Afterpay's Salesforce Reference Architecture (SFRA) cartridge as well as the `app_storefront_base` cartridge. That means the template in Cash App Afterpay's cartridge will override the base template.

Since Cash App Afterpay's cartridge was built to work with the base cartridge, this override should be fine. However, if you've made custom changes to these templates in the base cartridge, or have installed plugins which override these templates, you must merge these changes yourself.

It may be useful to refer to that version to see the Cash App Afterpay-specific changes in the overridden file. In general, comments have been left in the files to make it easier to identify Cash App Afterpay-specific changes vs. base-SFRA content.

| Template File                   | Location & Purpose for Change                                                                                                                                                                                                                                                                                                      |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cart.isml`                     | `cartridge/templates/default/cart/cart.ismlIncludes /js/afterpay.js` and `/css/afterpaystyle.js`<br />Default error messaging on page will also display Cash App Afterpay-specific error messages.                                                                                                                                 |
| `cartTotals.isml`               | `cartridge/templates/default/cart/cartTotals.ismlDisplay` <br />Cash App Afterpay messaging under cart totals on the cart page.                                                                                                                                                                                                    |
| `checkoutButtons.isml`          | `cartridge/templates/default/cart/checkoutButtons.isml` <br />Display Cash App Afterpay Express Checkout Button on the cart page.                                                                                                                                                                                                  |
| `paymentOptionsTabs.isml`       | `cartridge/templates/default/checkout/billing/paymentOptions/paymentOptionsTabs.isml` <br />Adds a payment tab for Cash App Afterpay and/or Cash App Pay                                                                                                                                                                           |
| `paymentOptionsContent.isml`    | `cartridge/templates/default/checkout/billing/paymentOptions/paymentOptionsContent.isml` <br />Include content displayed in the Cash App Afterpay and/or Cash App Pay payment tab.                                                                                                                                                 |
| `paymentOptionsSummary.isml`    | `cartridge/templates/default/checkout/billing/paymentOptions/paymentOptionsSummary.isml`<br />Include content displayed in the payment summary when Cash App Afterpay and/or Cash App Pay is the payment method.                                                                                                                   |
| `confirmationPaymentInfo.isml`  | `cartridge/templates/default/checkout/confirmation/confirmationPaymentInfo.isml` <br />Included Cash App Afterpay or Cash App Pay in the payment confirmation.                                                                                                                                                                     |
| `checkout.isml`                 | `cartridge/templates/default/checkout/checkout.isml`<br />Make all default SFRA checkout buttons hideable with CSS. Add the Cash App Afterpay and/or Cash App Pay checkout button. Add Cash App Afterpay Checkout Widget. Include Cash App Afterpay and Cash App Pay client-side JS (JavaScript) and CSS (Cascading Style Sheets). |
| `scripts.isml`                  | `cartridge/templates/default/common/scripts.isml`<br />Adds JS files required to load the Cash App Afterpay assets.                                                                                                                                                                                                                |
| `pageFooter.isml`               | `cartridge/templates/default/components/pageFooter.isml`<br /> Adds Cash App Afterpay among the accepted payment methods in the footer.                                                                                                                                                                                            |
| `addToCartButtonExtension.isml` | `cartridge/templates/default/product/components/addToCartButtonExtension.isml` <br />Add express checkout buttons on the PDP page.                                                                                                                                                                                                 |
| `setItems.isml`                 | `cartridge/templates/default/product/components/setItems.isml`                                                                                                                                                                                                                                                                     |
| `bundleDetails.isml`            | `cartridge/templates/default/product/bundleDetails.isml`<br /> Add Cash App Afterpay messaging for bundles. Include Afterpay JS / CSS.                                                                                                                                                                                             |
| `productDetails.isml`           | `cartridge/templates/default/product/productDetails.isml`<br /> Include Cash App Afterpay JS/CSS. Display Cash App Afterpay messaging on product details page.                                                                                                                                                                     |
| `productTile.isml`              | `cartridge/templates/default/product/productTile.isml`<br /> Display Cash App Afterpay messaging on product tile.                                                                                                                                                                                                                  |
| `quickView.isml`                | `cartridge/templates/default/product/quickView.isml`<br /> Display Cash App Afterpay messaging on quick view.                                                                                                                                                                                                                      |
| `setDetails.isml`               | `cartridge/templates/default/product/setDetails.isml`<br /> Include Cash App Afterpay JS/CSS.                                                                                                                                                                                                                                      |
| `setQuickView.isml`             | `cartridge/templates/default/product/setQuickView.isml`                                                                                                                                                                                                                                                                            |
| `catLanding.isml`               | `cartridge/templates/default/rendering/category/catLanding.isml`<br /> Include Cash App Afterpay JS/CSS.                                                                                                                                                                                                                           |
| `searchResults.isml`            | `cartridge/templates/default/search/searchResults.isml`<br /> Include Cash App Afterpay JS/CSS.                                                                                                                                                                                                                                    |

Similarly, if you’ve made customizations to the following JS (JavaScript) and SCSS (Salesforce Cascading Style Sheet) files, you may need to merge the Cash App Afterpay changes.

| JS File          | Location & Purpose for Change                                                                |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `checkout.js`    | `cartridge/client/default/js/checkout.js` <br />Include Cash App Afterpay client-side JS.    |
| `productTile.js` | `cartridge/client/default/js/productTile.js` <br />Include Cash App Afterpay client-side JS. |

| SCSS File       | Location                                                                                                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `homePage.scss` | `cartridge/client/default/scss/homePage.scss` <br /> Adds CSS for Cash App Afterpay’s checkout button. Specifically used by the minicart when opened on the store home page. |

---

# Getting Started

<Info title="Migrate from Afterpay to Cash App Afterpay">
  If you are an Afterpay merchant, see the 

  [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/shopify-migration)

   for information on the migration from Afterpay to Cash App Afterpay.
</Info>

---

# Add Cash App Afterpay to my Shopify Store

Follow the instructions and section links below:

* [Add Cash App Afterpay at Checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-afterpay-at-checkout)

* [Cash App Afterpay On-Site Messaging App](/cash-app-afterpay/guides/platforms/shopify/cash-app-afterpay-on-site-messaging-app)

* [Cash App Afterpay Code Snippet](/cash-app-afterpay/guides/platforms/shopify/manually-add-cash-app-afterpay-site-messaging-to-theme)

* [Cash App Afterpay Banner](/cash-app-afterpay/guides/platforms/shopify/add-a-cash-app-afterpay-banner-to-shopify)

* [Join the Shop Directory](../../MARKETING/Shop-Directory.md)

* [Find Cash App Afterpay Brand Assets](../../MARKETING/Brand-Assets.md)

* [Add Cash App Pay at Checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-pay-at-checkout)

* [Find Cash App Pay Brand assets](/cash-app-pay-partner-api/guides/resources/cash-app-pay-assets)

***

## Supported Countries

Cash App Afterpay is available for Shopify merchants with a store address in the USA only. The same restriction applies to Cash App Pay.

## Store Address

The store address must correspond to the Cash App Afterpay account region.

Do the following:

1. Go to *Shopify Admin* > *Settings* > *General*.

2. Under **Store Address**, the **Country** must be United States.

![Shopify-1](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-1.png)

## Store Currency

The store currency must correspond to the Cash App Afterpay account region.

To set the store currency:

1. Go to: *Shopify Admin* > *Settings* > *General*.

2. Under **Standards and formats**, the **Currency** must be United States Dollars (USD).

![hopify-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shopify-2.png)

## Payment Settings

Check if you have **Automatically at checkout** or **Automatically when order is fulfilled** enabled.

![shopify-get-started-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shopify-get-started-1.png)

In the Payment Settings, you can also apply manual capture for all payment types. If you have enabled **Manually**, follow these instructions:

[Shopify Manual Capture](/cash-app-afterpay/guides/platforms/shopify/shopify-manual-capture)

## Next Steps

Go to the [Add Cash App Afterpay at Checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-afterpay-at-checkout) page and add Cash App Afterpay to your checkout pages.

---

# Add Cash App Afterpay at Checkout

Before you start, ensure that you have Shopify installed and working.

<Info>
  The Shopify App Store listing and app logo will reflect the new Cash App Afterpay brand, while the payment app itself continues to be called **Afterpay US**. Your customers will see the updated branding at checkout.

  For a list of requirements before you add Cash App Afterpay, see the [Requirements](#requirements) section at the bottom of this page.
</Info>

## Overview

The Cash App Afterpay integration process can be completed in three stages:

* [Download the Afterpay US payment app](#download-the-afterpay-us-payment-app)
* [Connect your Business Hub account](#connect-your-business-hub-account)
* [Confirm and activate](#confirm-and-activate)

## Download the Afterpay US payment app

Do the following:

1. Click [here](https://accounts.shopify.com/store-login?redirect=settings%2Fpayments/alternative-providers/84934657) to download the Afterpay US payment app.
2. When the **Install app** screen appears, click **Install**.
3. Once installed, Afterpay US (New) appears in your list of apps.

## Connect your Business Hub account

After you install the Afterpay US app, you are automatically redirected to the Business Hub to verify your merchant account.

Follow these steps to connect your account:

### Step 1: Log into Business Hub

Log into your Business Hub user account.

<Tip>
  If you have trouble accessing your Business Hub account, try [resetting your password](https://hub.us.afterpay.com/forgot-password). If you need an account to be created, contact your team's main internal onboarding contact.
</Tip>

### Step 2: Select your merchant account

1. From the dropdown menu, select the merchant account that should be associated with your storefront.
2. Ensure that this is the correct account for your specific Shopify store.

### Step 3: Complete connection

1. Click the **Connect** button to link your Business Hub merchant account with Shopify.
2. Wait for the connection process to complete.
3. Once you have a successful connection, you're automatically returned to Shopify.

## Confirm and activate

After successfully verifying your Business Hub merchant account, you return to Shopify. A screen appears with two toggle switches and a *More actions* menu. Do the following:

1. Activate the payment gateway. Keep **Test mode** inactive, and click **Activate**. This screenshot shows the result:

   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Cash-AfterpayUS-activated.png" />

   <Warning>
     **Do not enable Test mode.**

      If you enable Test mode, the integration fails. The 

     **Enable test mode**

      function is only for use on dedicated test websites. Contact your Afterpay Account Manager if you need test credentials.
   </Warning>
2. Go to your online store and verify that Afterpay is a checkout option.

### Managing merchant integration

If you ever need to change which merchant account is connected to your Shopify store, it's a simple process:

1. In your Shopify admin, go to Settings → Payments
2. Click into the Afterpay US (New) payment app
3. Then, click More actions → Manage
4. This will take you back to the Business Hub where you can select a different merchant account
5. Choose the new account you want to use and click Connect

That's it! The new merchant account will now be connected to your Shopify store.

## Requirements

To avoid issues installing the new Afterpay US app, check that you have Shopify installed and working.

Make sure that your company or organization meets the following requirements:

Your business address is in one of the the following:

* Australia
* Canada
* Hong Kong SAR
* New Zealand
* United Kingdom
* United States

You must ship to the United States.

You must accept USD (United States Dollars) as a currency.

---

# Add Cash App Pay at Checkout

Cash App Pay is a fast and simple payment method that lets customers pay for purchases either by scanning a simple QR code or by tapping Cash App Pay at checkout to be redirected to Cash App.

You can use your existing Cash App Afterpay integration to enable this feature, and it works on Desktop, Mobile, and in a native app.

**Prerequisites**

Before you integrate Cash App Pay into Shopify ensure that you are:

* An existing Cash App Afterpay merchant on Shopify with a proven integration

* A US merchant

<Info>
  Cash App Pay will appear as another payment option on your payment page alongside Cash App Afterpay. It will <em>not</em> be just a tender type within a Cash App Afterpay payment.
</Info>

## Overview

The Cash App Pay integration process can be completed in three stages:

* [Download the Cash App Pay payment application](#download-the-cash-app-pay-payment-application)

* [Connect your Account](#connect-your-account)

* [Final Confirmation and Activation](#final-confirmation-and-activation)

<Warning>
  You must use your Cash App Afterpay production merchant ID and your Cash App Afterpay production secret Key in the Cash App Pay integration process. Your sandbox credentials will not work for account activation, even if you are in a sandbox environment.
</Warning>

## Download the Cash App Pay payment application

1. Go to the [Cash App Pay](https://apps.shopify.com/cash-app-pay) page on the Shopify App Store.

2. Login to Shopify.

3. Download the Cash App Pay application. The Install app screen appears. See the picture below:

![cap-shop-payment-app-activation-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cap-shop-payment-app-activation-1-2.png)

4. Shopify asks you to grant Cash App Pay (Cash App Afterpay) permission to *View personal data* and *View and edit store data*. Click **Install** to continue.

## Connect your account

To connect your account, do the following:

1. After downloading and installing the Cash App Pay app, from the following screen, click **Connect to Cash App Pay**.

![cap-shop-payment-app-activation-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cap-shop-payment-app-activation-2.png)

2. The *Connect to Cash App Pay* screen appears:

![cap-shop-payment-app-activation-3-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cap-shop-payment-app-activation-3-small.png)

3. Enter your Cash App Afterpay production merchant ID in the **Merchant ID** field.

4. Enter your Cashs App Afterpay production secret key in the **Secret Key** field.

5. Click **Continue**.

<Warning>
  In step 3 above, you must use your Cash App Afterpay 

  **Production**

   merchant ID. In step 4 above, you must use your Cash App Afterpay 

  **Production**

   secret key. Your Sandbox credentials 

  **will not work**

   for account activation, even if you are in a Sandbox environment.
</Warning>

## Final Confirmation and Activation

After you click **Continue** in Step 5 above, you are redirected to the following page for final confirmation:

![cap-shop-payment-app-activation-4-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cap-shop-payment-app-activation-4-small.png)

Do the following:

1. Ensure the *Cash App Pay* toggle switch is enabled (black).

2. Ensure *Test Mode* is off (grey).

3. Click **Activate**.

Your customers should now have Cash App Pay available as a payment method alongside Cash App Afterpay at checkout.

!\[Screenshot 2025-03-20 at 4.22.03 PM.png]\(../../../assets/images/Screenshot 2025-03-20 at 4.22.03 PM.png)

---

# Shopify Afterpay On-Site Messaging App

<Warning title="Important">You cannot use the Afterpay On-site Messaging App to add Cash App Afterpay at checkout. Instead, follow the instructions on the [Add Afterpay at Checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-afterpay-at-checkout) page.</Warning>
<Warning title="Important">Before you install and configure the Afterpay On-Site Messaging App, make sure you already added [Cash App Afterpay at checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-afterpay-at-checkout) on your Shopify store. Ensure Cash App Afterpay is visible at checkout and functioning before you attempt anything with the Afterpay On-Site Messaging App. You cannot use the Afterpay On-Site Messaging App without first adding Cash App Afterpay at checkout successfully.</Warning>
This page shows you how to do the following:

* [Install the Afterpay On-site Messaging App](#install-the-cash-app-afterpay-on-site-messaging-app) - A procedure to install the app

* [Add the Messaging to the Product Pages](#add-the-messaging-to-the-product-pages) - Instructions on how to add the messaging to the Product Pages

* [Add the Messaging to the Cart Page](#add-the-messaging-to-the-cart-page) - Instructions on how to add the messaging to the shopping Cart Page

* [Adjust the Style of Messaging](#adjust-the-style-of-messaging) - This covers things like text alignment, margins, text color, logo types, display for mobile devices, and more

* [Make Mobile View Adjustments](#mobile-view-adjustments) - Adjust the style of messaging for mobile devices

* [Hide Messaging from Some Products](#hide-messaging-from-some-products) - Select products that you don't want to associate with Afterpay Messaging

<Note>
  This information is for Shopify 2.0 themes only.
</Note>

## Install the Afterpay On-site Messaging App

Do the following:

1. Click the [link](https://apps.shopify.com/afterpay-messaging) to download and install the Afterpay On-Site Messaging app from the Shopify App Store.

2. Click **Install**. An installation screen on Shopify's admin portal appears.

   ![shop-app-install-A.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-app-install-A.png)

3. Click **Install**.

   ![shop-app-install-B.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-app-install-B.png)

   <Note>
     If you clicked 

     **Install**

      and your screen doesn’t show the 

     **Connect**

      button, your Cash App Afterpay account is already fully registered. You can skip steps 4 to 7 (inclusive) below and go straight to the 

     [Add the Messaging to the Product Pages](#add-the-messaging-to-the-product-pages)

      section.
   </Note>

4. Click **Connect** next to *Connect the Cash App Afterpay account*. You are taken to a get.afterpay.com URL, where the email is prefilled with the email on your Shopify store.

   ![shop-app-install-C.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-app-install-C.png)

5. Send the email and Cash App Afterpay will email you a login link to the Cash App Afterpay dashboard.

   ![shop-app-install-D.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-app-install-D.png)

6. Login to your Cash App Afterpay dashboard and ensure you have completed all the registration steps.

7. When Cash App Afterpay registration is complete, click the **Show me how** button under *Add Afterpay messaging*, at the bottom of the [get.afterpay.com](http://get.cashappafterpay.com) status page.

   ![step-7-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/step-7-small.png)

## Add the Messaging to the Product Pages

1. Once it is installed, you need to open the *Afterpay On-Site Messaging app*. To do this, go to [Shopify Admin](https://admin.shopify.com/). Then go to *Apps* and select *Afterpay On-Site Messaging*.

   ![shop-message-app-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-1.png)

2. From the app's *Add Messaging* section, click [Open Theme Editor](https://accounts.shopify.com/lookup?rid=cb901599-a4cd-4d01-9e88-e70243d0636c).

   ![shop-message-app-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-2.png)

3. From the Theme editor, click the dropdown at the top of the editor, then click *Products*.

   ![shop-message-app-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-3.png)

4. Select the *Default* product template, or the Product template that needs messaging.

   ![shop-message-app-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-4.png)

   > **How Messaging Works**
   >
   > Messaging works on Product Page templates. So if you have a single Product Page template, you add messaging to that template. If you have several different Product Page templates, then you'll need to add messaging to each one separately.

5. Move your mouse over the Product price, a + symbol appears.

   !\[Shopify OSM App - Product Pages - Step 5.png]\(../../../assets/images/Shopify OSM App - Product Pages - Step 5.png)

6. Click **Add block** and then select *Payments Messaging - Afterpay On-Site Messaging*.

   Your product page should now look like this:

   !\[Shopify OSM App - Product Page Example.png]\(../../../assets/images/Shopify OSM App - Product Page Example.png)

7. Click **Save** in the top right corner.

   ![shop-message-app-9.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-9.png)

## Add the Messaging to the Cart Page

<Warning>Never try to use the app to add Cash App Afterpay to the checkout page.</Warning>
You are now ready to add some messaging to the Cart page. Do the following:

1. For an accurate Cart page preview, click **Add to cart**.

   !\[Shopify OSM App - Product Pages - Step 7 screenshot 2 (alt).png]\(../../../assets/images/Shopify OSM App - Product Pages - Step 7 screenshot 2 (alt)-2.png)

2. Next, to open the Cart page, click the dropdown at the top of the editor and click **Cart**.

   ![shop-message-app-b.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-b.png)

3. Move the mouse over the Subtotal above the Checkout button. A *+* symbol appears.

   !\[Shopify OSM App - Cart Page - Step 3 to 5.png]\(../../../assets/images/Shopify OSM App - Cart Page - Step 3 to 5.png)

4. Click **Add Block** and select *Afterpay On-Site Messaging*.

5. If the text alignment is wrong, adjust the text alignment. To do this, click the *Text Alignment* dropdown and select a new alignment option.

   !\[Shopify OSM App - Cart Page - Step 6.png]\(../../../assets/images/Shopify OSM App - Cart Page - Step 6.png)

**Mobile View**

You can set a separate alignment for display on mobile devices.

Do the following:

1. To check the appearance on a mobile device, click the monitor icon and then click *Mobile* at the top right of the editor.

   ![shop-message-app-mobile.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-mobile.png)

2. Scroll down to *Mobile View* settings, make any changes you need.

3. Click **Save** in the top right corner.

4. Verify your messaging and alignment on your live store.

You can adjust various aspects of the page for mobile devices. See the [Mobile View Adjustments](#mobile-view-adjustments) section below for more details.

## Adjust the Style of Messaging

You can adjust many aspects of the styling. To do this:

1. Select the *Payments Messaging - Afterpay On-Site Messaging* block on the Product page.

   !\[Shopify OSM App - Style Messaging - Step 1.png]\(../../../assets/images/Shopify OSM App - Style Messaging - Step 1.png)

   Alternatively you can select *Payments Messaging - Afterpay On-Site Messaging* from the side bar under *Product information*. See picture below:

   ![shop-message-app-adjust-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-message-app-adjust-2.png)

### Text Alignment

To adjust the text alignment:

1. Click the *Text Alignment* dropdown and select a new alignment option.

   !\[Shopify OSM App - Text Alignment - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Text Alignment - Screenshot 1.png)

### Margins

To adjust the margins above and below the messaging:

1. Enter a new value into the *Margin Top* field.

2. Enter a new value into the *Margin Bottom* field.

   <br /><br />Negative values are allowed.

   !\[Shopify OSM App - Margins - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Margins - Screenshot 1-2.png)

### Text Color

To adjust the text color:

1. Click the *Text Color* color-picker and select the new text color.

   !\[Shopify OSM App - Text Color - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Text Color - Screenshot 1-2.png)

### Text Size

To adjust the text size:

1. Click the *Text Size* dropdown and select a new text size option, extra small, small, medium and large.

   !\[Shopify OSM App - Text Size - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Text Size - Screenshot 1.png)

### Text

To adjust the intro text:

1. Click the \*Intro Text dropdown and select a new intro text option.

   !\[Shopify OSM App - Intro Text - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Intro Text - Screenshot 1.png)

### Show/Hide "Interest Free"

To show or hide the interest-free phrase:

1. Enable or disable the *Show "interest-free"* checkbox.

   !\[Shopify OSM App - Show Interest Free - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Show Interest Free - Screenshot 1.png)

The default value is enabled - the phrase *interest-free* appears to your customers. In the picture above, the checkbox is blank, so no *interest-free* message appears to your customers.

### Payment Amount

To show or hide the payment amount in bold:

1. Enable or disable the *Bold Payment Amount* checkbox.

   !\[Shopify OSM App - Bold Amount - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Bold Amount - Screenshot 1.png)

The default value is enabled - the payment amount is in bold. In the picture above, the checkbox is blank, so the payment amount does not appear in bold to your customers.

### Show/hide "with"

The word "with" appears between the price and the Cash App Afterpay logo or badge. See the [Logo Type](#logo-type) below. To show or hide the word "with" do the following:

1. Enable or disable the Show "with" checkbox.

   !\[Shopify OSM App - Show With - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Show With - Screenshot 1.png)

The default value is enabled - the word "with" appears between the price and the Cash App Afterpay logo or badge. In the picture above, the checkbox is blank, so the word with does not appear to your customers.

### Logo Type

To set the logo type:

1. Click the *Logo Theme* dropdown and select a new logo type.

   !\[Shopify OSM App - Logo Type - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Logo Type - Screenshot 1.png)

### Logo Theme

To set the theme of the logo:

1. Click the *Logo Theme* dropdown and select the new logo theme you want.

   !\[Shopify OSM App - Logo Theme - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Logo Theme - Screenshot 1.png)

### Modal Link Style

When a customer clicks on the modal link, a pop-up window appears with more information about Cash App Afterpay. The default symbol for the modal link is a circled info icon ⓘ.

To change or hide the modal link:

1. Click the *Modal Link Style* dropdown and select the new modal link option.

   !\[Shopify OSM App - Modal Link - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Modal Link - Screenshot 1.png)

## Outside Order Limits Messaging

The outside order limits messaging is a message displayed when the product price is outside the limits for Cash App Afterpay.

The default for these limits is $1.00 - $4,000.00 at present.

To adjust the outside order limits messaging:

1. Disable the *Show Lower Limit* checkbox to hide the lower limit.

2. Disable the *Show Upper Limit* checkbox to hide the upper limit.

3. Disable the *Show If Outside Limits* checkbox to hide outside order limits messaging completely.

   !\[Shopify OSM App - Order Limits - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Order Limits - Screenshot 1.png)

<Note>
  Remember that the above settings only affect the messaging the customer sees. The settings do not affect whether customers can buy products at the checkout.
</Note>

## Mobile View Adjustments

You can set the styling separately for customers on mobile devices. To set the styling for mobile devices, do the following:

1. Click the monitor icon near the **Save** button.

2. Click the **Mobile** button that appears.

   ![mobile-set-mobile.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/mobile-set-mobile.png)

### Breakpoint

To adjust the screen width that defines the mobile view:

1. In the *Breakpoint* field, enter a new number in pixels.

   !\[Shopify OSM App - Mobile Breakpoints - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Mobile Breakpoints - Screenshot 1.png)

### Text Alignment

To adjust the text alignment for a mobile view:

1. Click the *Text Alignment* dropdown and select a new alignment option.

   !\[Shopify OSM App - Mobile Text Alignment - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Mobile Text Alignment - Screenshot 1.png)

### Margins

To adjust the margins above and below the messaging on a mobile view:

1. Enter a new number, this can be a negative number, into the *Margin Top* or *Margin Bottom* fields.

   !\[Shopify OSM App - Mobile Margins - Screenshot 1.png]\(../../../assets/images/Shopify OSM App - Mobile Margins - Screenshot 1.png)

## Footer Payment Icon

To place a payment icon on the footer (bottom) of the payment page, see the Footer Payment Icon section in the [Shopify FAQ](/cash-app-afterpay/guides/platforms/shopify/faq)

## Hide Messaging from Some Products

When you have enabled the On-Site Messaging App, you can also hide Afterpay Messaging from certain products. To do this, use the Theme Editor to create a new template. Next you go to the Product section and choose the products that you don't want associated with messaging. Then you assign these selected product(s) to the new template and make sure no messaging is applied to that template.

To create the template:

1. Go to the On-Site Messaging App.

2. Open the Theme Editor.

3. Click the Home Page dropdown, and then select *Products*. See the picture below:

   ![hide-message-new-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/hide-message-new-1.png)

4. Select *Create Template*.

5. Enter a name for this new template. See the picture below:

   ![hide-message-3-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/hide-message-3-new.png)

You have now created your template and named it. Your next task is to fill this template with the product, or products, that you don't want to have Afterpay messaging.

Do the following:

1. Go to [Shopify admin](https://accounts.shopify.com/lookup?rid=d3c85713-691d-405c-a958-bde97cbf383e) and select *Products*.

2. Use the Search filter to find the product that you don't want to associate with Afterpay messaging. You can also find this product from the list of existing products. See the picture below:

   ![hide-message-4-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/hide-message-4-new.png)

3. In the Online store section, open the drop-down menu and select the new theme template you created. Then apply this new template to the product. See picture below:

   ![hide-message-5-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/hide-message-5-new.png)

4. Repeat step 3 for all the products that you don't want to associate with Afterpay messaging. Click **Save** when you have finished

5. Go back to On-Site Messaging App and open the *Theme Editor*.

6. Select the new template, then click *Afterpay Messaging* and delete it.

The Afterpay messaging for all the products assigned to the template is deleted.

---

# Manually Add Cash App Afterpay Site Messaging to Theme

---

# Manually Add Afterpay Site Messaging to Theme

**How can I add Afterpay Site Messaging to my Shopify product and cart pages?**

***

The Afterpay Code Snippet allows you, the merchant, to manually add Afterpay messaging to the product and cart pages. You do this by copy-pasting a code snippet into your Shopify liquid template file. This is a short procedure that consists of a few steps.

This page shows you how to do the following:

* [Configuration](#configuration)

* [Add an Afterpay Banner to Shopify](#add-an-afterpay-banner-to-shopify)

* [Add messaging to the dynamic or er cart](#add-messaging-to-the-dynamic-or-drawer-cart)

## Configuration

Do the following to position the Afterpay site messaging onto the product and cart pages of your Shopify website:

1. Copy the code below to your clipboard, a **Copy to Clipboard** icon in the top right corner makes this easy.

```js
<!-- Begin Shopify-Afterpay JavaScript Snippet (v1.2.1) -->
{% if cart.currency.iso_code == shop.currency %}
<script type="text/javascript">
// Overrides:
// var afterpay_msg_size = 'sm';  // Can be 'xs', 'sm', 'md' or 'lg'.
// var afterpay_bold_amount = true;
// var afterpay_logo_theme = 'colour';  // Can be 'colour', 'black' or 'white'.
// var afterpay_modal_open_icon = true;
// var afterpay_hide_upper_limit = false;
// var afterpay_hide_lower_limit = true;
// var afterpay_show_if_outside_limits = true;

// var afterpay_product_integration_enabled = true;
// var afterpay_product_selector = '#product-price-selector';
// var afterpay_variable_price_fallback = false;
// var afterpay_variable_price_fallback_selector = '';
// var afterpay_variable_price_fallback_method = 'mutation';  // Can be 'mutation' or 'interval'.

// var afterpay_cart_integration_enabled = true;
// var afterpay_cart_static_selector = '#cart-subtotal-selector';
// var afterpay_variable_subtotal_fallback = false;
// var afterpay_variable_subtotal_fallback_selector = '';
// var afterpay_variable_subtotal_fallback_method = 'mutation'; // Can be 'mutation' or 'interval'.

// var afterpay_dynamic_cart_integration_enabled = false;
// var afterpay_dynamic_cart_selector = '.cart-drawer__footer .totals';
// var afterpay_dynamic_cart_observer_target = '#CartDrawer';

// var afterpay_footer_logo_enabled = true;
// var afterpay_footer_logo_format = 'icon';  // Can be 'icon', 'stacked' or 'logo'.
// var afterpay_footer_logo_theme = 'colour'; // Can be 'colour', 'black' or 'white'.
// var afterpay_footer_logo_background = 'border';  // Can be 'border' or 'transparent'.
// var afterpay_footer_logo_container = 'footer ul.payment-icons';
// var afterpay_footer_logo_template = '<li class="payment-icon"><object data="{logo_path}" type="image/svg+xml"></object></li>';

// Non-editable fields:
var afterpay_js_language = {{ localization.language.iso_code | slice: 0, 2 | json }};
var afterpay_js_country = {{ localization.country.iso_code | json }};
var afterpay_shop_currency = {{ shop.currency | json }};
var afterpay_cart_currency = {{ cart.currency.iso_code | json }};
var afterpay_shop_money_format = {{ shop.money_format | json }};
var afterpay_shop_permanent_domain = {{ shop.permanent_domain | json }};
var afterpay_theme_name = {{ theme.name | json }};
var afterpay_product = {{ product | json }};
var afterpay_product_collections = {{ product.collections | map: 'title' | join: ',' | json }};
var afterpay_current_variant = {{ product.selected_or_first_available_variant | json }};
var afterpay_cart_total_price = {{ cart.total_price | json }};
var afterpay_cart_skus = {{cart.items | map: 'sku' | join: ',' | json }};
var afterpay_cart_collections = {{cart.items | map: 'product' | map: 'collections' | map: 'title' | uniq | join: ',' | json }};
var afterpay_js_snippet_version = '1.2.1';
</script>
<script type="text/javascript" src="https://static.afterpay.com/shopify-afterpay-javascript.js"></script>
{% else %}
<!-- Afterpay disabled: {{ cart.currency.iso_code }} != {{ shop.currency }} -->
{% endif %}
<!-- End Shopify-Afterpay JavaScript Snippet (v1.2.1) -->

```

2. Login to [Shopify Admin](https://accounts.shopify.com/lookup?rid=edf4fd64-060c-48a7-bf95-095eb87b831c)

3. Navigate to **Themes**. To do this, go to **Sales channels** > **Online Store** > **Themes**.

   ![shopify-ap-site-mess-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shopify-ap-site-mess-1.png)

4. Navigate to the current theme, then go to **Actions** > **edit code**.

   ![shop-ap-site-mess-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shop-ap-site-mess-2.png)

5. Under the **Layout** folder, click **theme.liquid**.
   ![step5.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Step_5.png)

6. Scroll to the bottom of the `theme.liquid` file:

   ![step5.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Step_6.png)

7. Paste the copied text (Step 1), at the bottom of the `theme.liquid` file:

8. Click **Save**, and go to the website to review the product and cart pages for Afterpay assets.

   !\[Shopify Manually Add Messaging - Config - Step 7 Screenshot.png]\(../../../assets/images/Shopify Manually Add Messaging - Config - Step 7 Screenshot.png)

<Note>
  Shopify have a help topic on editing Liquid files 

  [here](https://shopify.dev/docs/api/liquid)

  .
</Note>

## Add an Afterpay Banner to Shopify

To add an Afterpay Banner to your Shopify page, follow the instructions [here](/cash-app-afterpay/guides/platforms/shopify/add-a-cash-app-afterpay-banner-to-shopify).

## Add messaging to the dynamic or drawer cart

To add messaging to the dynamic or drawer cart, do the following:

1. Follow all the [Configuration](#configuration) steps above from step 1 to step 8.

2. Navigate to your `theme.liquid file`.

3. Find the required selector on the drawer cart.

4. Add the selector to the code and enable the dynamic cart integration.

### Example Code snippet for Afterpay US

```js

// var afterpay_dynamic_cart_integration_enabled = true;

// var afterpay_dynamic_cart_selector = '.cart-drawer__footer .totals';

// var afterpay_dynamic_cart_observer_target = '#CartDrawer';

```

### Example of code with selectors

```js
var afterpay_dynamic_cart_integration_enabled = true;
var afterpay_dynamic_cart_selector = '.total';
var afterpay_dynamic_cart_observer_target = '#CartDrawer';
```

---

# Shopify Manual Capture

CashApp Afterpay’s integration enables you to leverage Shopify’s manual capture setting.

<Info>
  This is a Shopify store-wide setting, so if you have it enabled for another payment method it is enabled for the new payment gateway.
</Info>

If you enable *Manually capture payment for orders* within your Shopify payment settings, this means the following:

**Cash App Afterpay will not automatically capture orders when the customer completes checkout**

* Instead, Cash App Afterpay will place an authorization hold on the customer’s account like other payment methods

* Unlike other payment methods, the customer’s installment plan begins as soon as the authorization is made

* Most customers are charged for their first installment at this time, unless they qualify for Cash App Afterpay’s *No payment Up-Front* program. This is where the first installment is collected two weeks after the authorization is made

* Cash App Afterpay’s authorization hold is **valid for a period of 13 days from the time of authorization**. If the order has not been captured before this time, any uncaptured amount is automatically voided. This voided amount is subtracted from the Cash App Afterpay customer’s outstanding balance of the order. Sometimes the voided amount is more than the customer’s outstanding balance of the order. In this case the customer is refunded the remainder of the voided amount, up to the authorized amount. For more information on refunds, see the [Cash App Afterpay help](https://help.afterpay.com/hc/en-us/articles/360031623571-How-do-refunds-and-returns-work-at-Afterpay)

**Capture orders through the Shopify order tab, integrations, or direct through Shopify’s API**

* You can use all the available options on Shopify to capture Cash App Afterpay orders as any other payment method supporting manual capture

* **If you capture orders through a third-party integration or through Shopify’s API, you may need to extend your configurations to capture Cash App Afterpay orders**.

* If you capture orders through Shopify’s order tab, you will now need to capture Cash App Afterpay orders. See the [Shopify help on how to manually capture payments](https://help.shopify.com/en/manual/orders/get-paid#capture-payments-manually)

* **Shopify will continue to restrict orders to a single capture**. This means that any uncaptured amounts will expire and are voided on the 14th day after the original authorization

**To cancel an authorised order, you can use all the methods that Shopify allows (orders tab, integrations or Shopify’s API)**

* See the [Shopify help on how to manually capture payments](https://help.shopify.com/en/manual/orders/get-paid#capture-payments-manually)

* Shopify will continue to restrict cancellations to only apply to the full order amount - Shopify does not support partial cancellations

**Refunds will continue as normal**

* For partially captured orders, only the captured amount is available to be refunded

**You will only be settled for funds that you have captured**

---

# Shopify Order Reconciliation

Reconcile Afterpay US (New) or Cash App Pay orders on Shopify and ensure all transactions are accounted for.

This page consists of six sections:

* [Search for a specific order in Shopify](#search-for-a-specific-order-in-shopify)
* [Reconcile orders from Shopify Orders export](#reconcile-orders-from-shopify-orders-export)
* [Search for all orders by payment method in Shopify](#search-for-all-orders-by-payment-method-in-shopify)
* [Export all orders by payment method in Shopify](#export-all-orders-by-payment-method-in-shopify)
* [Search for country-specific orders in Shopify](#search-for-country-specific-orders-in-shopify)
* [Create custom report by payment method](#create-custom-report-by-payment-method)

<Note>
  Shopify provide a detailed guide to 

  [Searching, viewing, and printing orders](https://help.shopify.com/en/manual/orders/manage-orders/search-view-print-orders)

  . Use this Shopify guide along with the information on this page.
</Note>

## Search for a specific order in Shopify

To find a specific order, do the following:

1. Go to *Shopify Admin* > *Orders*.

2. Enter the following in the *Orders* search bar, that is the search bar called *Filter Orders*: `receipt.payment_id:`

3. Copy the *Merchant Order No.* from the [Business Hub](https://hub.us.afterpay.com/us) and paste it in search bar after `receipt.payment_id:`

Here is an example in the Shopify *Orders* tab:

![search-for-a-specific-order-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/search-for-a-specific-order-new.png)

To access the Shopify Admin, use this [URL](http://shopify.com/admin/orders?query=receipt.payment_id%3A).

## Reconcile orders from Shopify Orders export

To reconcile orders from the export, do the following:

1. Go to *Shopify Admin* > *Orders*

2. Optional: Enter **afterpay** in the Orders search bar.

3. Optional: Enter **"cash app pay"** in the Orders search bar. Notice the quotes for an exact match.

   ![cash-app-pay.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cash-app-pay.png)

4. Click **Export**.

5. Towards the right side of the exported table, a *Payment ID* column is now available. For both Afterpay US (New) and Cash App Pay orders, this column is populated with the Merchant Reference No. from the [Business Hub](https://hub.us.afterpay.com/us).

For example, here is a Shopify export file:

{/* <img alt="Shopify export file" src="../../../assets/images/Screenshot 2025-03-25 at 10.55.00 AM.png" width="400px"> */}

For example, within the Business Hub the information appears like this:

<img alt="Shopify business hub" src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Screenshot 2025-03-25 at 10.50.01 AM.png" width="700px" />

## Search for all orders by payment method in Shopify

To search for all orders by payment method, do the following:

1. Go to *Shopify Admin* > *Orders*.

2. Enter **"Afterpay US (New)"** or **"Cash App Pay"** (include the quotation marks for an exact match) in the *Orders* search bar.

   ![search-for-all-orders.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/search-for-all-orders.png)

3. Click **Save as** to save this order filter.

<Info>
  If you use both the 

  **Afterpay US (New)**

   payment app and the 

  **Afterpay (New)**

   payment app, you can search for them separately.
</Info>

## Export all orders by payment method in Shopify

To export all your orders by payment method in Shopify, do the following:

1. Go to *Shopify Admin* > *Orders*.

2. Enter **"Afterpay US (New)"** or **"Cash App Pay"** (include the quotation marks for an exact match) in the *Orders* search bar.

3. Click the checkbox at the top of the column on the extreme left to select all the orders (see picture below) and click **Export** at the top right of the window.

   ![export.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/export.png)

4. The Export orders popup appears. Click the **Selected \[n] orders** radio button, and select what type of file you want for the exported data.

   ![export-orders.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/export-orders.png)

5. Click **Export orders**.

## Search for country-specific orders in Shopify

This is a useful way to identify cross-border trade (CBT) orders. Do the following:

1. Go to *Shopify Admin* > *Orders*.

2. Enter a search term in the search bar. For example, in the picture below, the search term is **canada afterpay**. This search shows all the Canadian Afterpay orders with their status and other information.

   ![country-specific.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/country-specific.png)

## Create custom report by payment method

If you use Advanced Shopify or Shopify Plus to host your store, you can use the Custom Report feature to find Afterpay US (New) and Cash App Pay orders.

To do this, you create and run a custom report for Orders by Payment Type. Start by going to your store's Shopify Admin page. Then go to *Analytics* > *Reports* > *Create custom report*.

For more information about how to run reports, see [this information](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports/report-types) from Shopify, along with [this information](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports/report-types/custom-reports) on custom reports.

---

# Shopify Test Mode

The Afterpay US payment app on Shopify supports a Test Mode. This means you are able to mock all supported transactions including:

* Authorizations
* Captures
* Voids
* Refunds

There are the following sections on this page:

* [Enable test mode for Afterpay US](#enable-test-mode-for-afterpay-us)

* [How do I know if Sandbox is enabled](#how-do-i-know-if-sandbox-is-enabled)

* [How to create a test order](#how-to-create-a-test-order)

* [Enable test mode for Cash App Pay](#enable-test-mode-for-cash-app-pay)

<Warning>
  Do not enable test mode on your live site. Once the payment method is activated in the store settings, it is live for customers to use. Only use a staging or development Shopify store for testing.
</Warning>

## Enable test mode for Afterpay US

<Info>
  **Note**

  Before you enable Test Mode, please complete the initial Afterpay US configuration. To do this, follow the steps to [Add Cash App Afterpay at Checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-afterpay-at-checkout) to verify your merchant account in the Business Hub.
</Info>

To enable the test mode for Afterpay US:

1. From your [Shopify admin](https://www.shopify.com/login), go to *Settings* > *Payments*.

2. In the *Additional payment methods* section, click **Afterpay US (New)**.

3. In the *Test mode* section, turn the toggle on. See the screenshot below:
   ![AfterpayUS\_testmode.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/AfterpayUS_testmode.png)

4. Click **Save**.

You're now ready to test Afterpay US transactions in your dedicated test store.

## How do I know if Sandbox is enabled

To check if Sandbox has been configured correctly, go to your test site and conduct a test transaction. Once it has been redirected to the Cash App Afterpay Login page, check the URL and it should be a Sandbox URL.

For example:

`portal.sandbox.afterpay.com/v2/checkout/en-AU/password`

## How to create a test order

For Cash App Afterpay transactions, follow the instructions [here](/cash-app-afterpay/guides/api-development/test-environments#test-customer-accounts) to create a sandbox customer account and mock various transaction approval outcomes.

For Cash App Pay transactions, creating test orders involves slightly different steps for desktop and mobile views.

* On desktop, you're taken to a page that displays a Cash App Pay QR Code. Scan this QR Code with your mobile device to decide whether to accept or decline the test order

* On mobile, you're automatically sent to a page where you can directly choose to accept or decline the test order

## Enable test mode for Cash App Pay

<Info>
  Before you enable Test Mode, please complete the initial Cash App Pay application configuration. To do this, follow the steps to [Add Cash App Pay at Checkout](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-pay-at-checkout) and use your production merchant credentials (Production Merchant ID and Production Secret Key). Once the Cash App Pay application is configured using your production merchant credentials, follow the steps below to enable the test mode for Cash App Pay.
</Info>

To test a Cash App Pay integration, do the following:

1. From your [Shopify admin](https://www.shopify.com/login), go to *Settings* > *Payments*.

2. In the *Additional payment methods* section, click **Cash App Pay**.

3. In the *Test Mode* section, click the toggle on. See the picture below:

   ![cap-shopify-payment-app-test-2-small.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cap-shopify-payment-app-test-2-small.png)

4. On the initial Cash App Pay setup screen, click **Test Mode**.

   ![Shopify-Test-mode.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Test-mode-2.png)

5. On the *Test Mode* screen, enter your sandbox credentials.

6. Enter your Cash App Afterpay Sandbox merchant ID in the *Sandbox Merchant ID* field.

7. Enter your Cash App Afterpay Sandbox secret key in the *Sandbox Secret Key* field.<br />

8. Click **Continue**.

![Shopify-Test-mode-success.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Shopify-Test-mode-success-2.png)

Your store is now ready to mock Cash App Pay transactions with your Sandbox credentials.

---

# Add a Cash App Afterpay Banner to Shopify

Banners display Cash App Afterpay information at the top of your Shopify page, as shown in the images below.

To add a Cash App Afterpay banner, you must edit your store's code. Before proceeding, ensure that:

* The [Afterpay US](https://apps.shopify.com/afterpay-us) payment app is already installed and running on your online store

* You have chosen a banner that aligns with the guidelines

<Info title="Recommendation">
  You are changing your online store's code, so be careful. We recommend you create a duplicate page and only publish it once you have verified the changes.
</Info>

## Steps to Add the Banner

1. Click **Actions** and select *Edit Code* from the drop-down menu.

2. Scroll down to *Sections* and click **Add a new section**.

3. In the *Create a new section called* field enter **cash-app-afterpay-banner**. The *cash-app-afterpay-banner.liquid* tab appears.

4. Delete the code that populates the *cash-app-afterpay-banner.liquid* tab.

### Add the Liquid file

1. Click the link to the [banner code snippet](https://static.afterpay.com/shopify-cash-app-afterpay-banner-liquid.html).

2. Click the **Copy to Clipboard** button.

3. Paste the banner code snippet into the *cash-app-afterpay-banner.liquid* tab.

4. Click **Save**.

### Editing the Theme Liquid file

1. Open the `theme-liquid` file.

2. Locate the line `{% sections 'header-group' %}` or `{% section 'header' %}`.

3. Add `{% section 'cash-app-afterpay-banner' %}` above this line. In the example below, it is added to line 4:

   ```
   <div class = "black-body"></div>
   {% section 'popup' %}
   {% section 'announcement-bar' %}
   {% section 'cash-app-afterpay-banner' %}
   {% section 'header' %}
   <div id="PageContainer" class="is-moved-by-drawer">
   ```

4. Click **Save**.

To verify the changes, click **Preview** and check for the banners appearance at the top of the page.

The images below illustrate a white, black, and green banner:

![white-banner-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/white-banner-new.png)

<br />

![black-banner-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/black-banner-new.png)

<br />

![green-banner-new.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/green-banner-new.png)

### Changing the Banner Color

To change the banner color:

1. Login to your **Shopify Admin** and navigate to your **Theme Settings** page: Go to **Online Store**> **Themes**.

2. Click **Customize** to change the theme with the Cash App Afterpay Banner.

   ![publish-customize.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/publish-customize.png)

3. Click **Cash App Afterpay Banner**.

   ![home-page.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/home-page.png)

4. Click **Banner color**.

5. Select **Black**, **White**, or **Green**.

   ![shopify-banner-for-caap.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shopify-banner-for-caap.png)

6. Click **Save**.

## Brand Assets

For more examples and information on brand assets, including banners, see the [Brand Assets](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets) section of this guide.

---

# Shopify FAQ

Frequently Asked Questions:

## Configuration and Setup

### Can’t verify your merchant account in the Business Hub?

You need **User** or **Hub Admin** permissions in the Business Hub to verify your merchant account. Make sure you have the right permissions before trying to connect your Business Hub account.

### Can't log in to the Business Hub?

If you've already installed the [Afterpay US payment app](/cash-app-afterpay/guides/platforms/shopify/add-cash-app-afterpay-at-checkout#download-the-afterpay-us-payment-app), you'll be redirected to the Business Hub to verify your merchant account.

If you're having trouble signing in:

* Use the [Forgot my password](https://hub.us.afterpay.com/forgot-password) link to reset your Business Hub password.
* Contact your team's main internal onboarding contact if you need general user account access created for the Business Hub

If you are still unable access the Business Hub, contact our Merchant Admin team by using the contact information below:

Email: [na-afterpay-merchant-admin@squareup.com](mailto:na-afterpay-merchant-admin@squareup.com)

Phone: +1 (484) 772-2736 | We are available Monday–Friday, 7:00am–4:00pm (PST).

Please make sure to provide the following information so that we can promptly help you:

* Your full name
* Merchant ID
* Trading/Business name
* Email address

***

### Why am I seeing "Your payment can't be processed for technical reasons. Please try a different payment method" at checkout?

This can occur when a customer checks out with Cash App Afterpay without entering an email address.

To prevent this from happening you can go to your [Shopify settings](https://www.shopify.com/admin/settings/checkout) and select **Customers can only check out using email**.

***

### Why are Cash App Afterpay orders not captured?

See the [Shopify Manual Capture](/cash-app-afterpay/guides/platforms/shopify/shopify-manual-capture) topic.

***

### Why can't I see Cash App Afterpay in my Express Checkout?

Cash App Afterpay is currently unavailable on Shopify Express Checkout.
If you navigate to the *Payment Methods* you should be able to view Cash App Afterpay.

If Cash App Afterpay is not visible on the Payment Methods, please contact your Cash App Afterpay Delivery Manager.

***

## Shopify Themes

### How do I add Cash App Afterpay to my theme?

See the instructions on the [Manually Add Cash App Afterpay Site Messaging to Theme](/cash-app-afterpay/guides/platforms/shopify/manually-add-cash-app-afterpay-site-messaging-to-theme) page.

***

### Why did Cash App Afterpay disappear from the Shopify product page after changing themes?

To display the Cash App Afterpay installment detail on the Shopify product pages, the active store theme is modified. When you change the Shopify theme, a new set of theme/template files is installed, which will not include the Cash App Afterpay product page display.

Although the product page display will require re-integration, Cash App Afterpay will remain active as a payment method on the Shopify checkout page.

To re-integrate the Cash App Afterpay product page display for the newly installed Shopify theme, please complete the steps outlined in the [Cash App Afterpay site messaging](/cash-app-afterpay/guides/platforms/shopify/manually-add-cash-app-afterpay-site-messaging-to-theme) topic.

***

### How do I add Cash App Afterpay to my payment icons?

To place a payment icon on the footer (bottom) of the payment page, first ensure that you have [enabled payment icons in your footer](https://help.shopify.com/en/manual/online-store/themes/themes-by-shopify/vintage-themes/customizing-vintage-themes/add-credit-card-icons#enable-payment-icons-in-your-footer).

Then do the following:

1. From your [Shopify admin](https://admin.shopify.com/), go to Online Store and select **Themes**.

   ![footer-payment-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/footer-payment-1.png)

2. Find the theme you want to edit, then click the **...** button to open the *Actions* menu. Click **Edit Code**.

   ![footer-payment-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/footer-payment-2.png)

3. In the *Sections* directory, click **footer.liquid**.

   ![footer-payment-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/footer-payment-3.png)

   If your theme doesn't include this file, click **theme.liquid** in the Layout folder.

   ![footer-payment-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/footer-payment-4.png)

4. Find the following code in the file:

   ```
   {% for type in shop.enabled_payment_types %}
   ```

5. Replace that line with the following two lines of code:

   ```liquid
   {% assign enabled_payment_types = "cashappafterpay" | concat: shop.enabled_payment_types %}
   {% for type in enabled_payment_types %}
   ```

6. Click **Save**

## <Note title="Code language">The code examples above are in [Liquid](https://shopify.github.io/liquid/basics/introduction) which is Shopify's own code language.</Note>

## Cash App Afterpay Banner

### How do I add a Cash App Afterpay banner myself?

If Cash App Afterpay messaging is already on your store and you would like to add a customizable Cash App Afterpay Banner, follow the instructions on the [Add an Cash App Afterpay Banner to Shopify page](/cash-app-afterpay/guides/platforms/shopify/add-a-cash-app-afterpay-banner-to-shopify).

***

## Orders

### Why was the customer returned to the Shopify checkout after trying to place an order with Cash App Afterpay?

A common cause for a customer being returned to the Shopify checkout page after trying to place an order with Cash App Afterpay is invalid order amount.

A customer's Cash App Afterpay transaction will not be approved should the order total be:

* Below the merchant minimum order value
* Above the merchant maximum order value
* In a non-supported currency

In any of these cases the customer is returned to the Shopify checkout page.

***

### How can I process a refund?

Cash App Afterpay orders can be refunded from Shopify and are automatically sent to Cash App Afterpay.

You can learn how to do refunds [here](https://help.shopify.com/en/manual/orders/refund-cancel-order).

***

### How do I update my store's minimum or maximum order value?

Please send an email with your request to [merchantAdminUS@afterpay.com](mailto:merchantAdminUS@afterpay.com)

***

### Why is the amount different between a Shopify order and Cash App Afterpay after capture?

This occurs if the cart is modified after the customer is redirected to Cash App Afterpay to complete the order.

<Note>This issue has been resolved by Shopify's Checkout Extensibility. If you are affected by this issue, it is likely that you still use Shopify's older checkout platform, called *checkout.liquid*. According to Shopify, they will have contacted you about migration to the latest Checkout Extensibility platform. As the *checkout.liquid* platform deprecated on August 13th 2024, we urge you to use Shopify's latest checkout platform to avoid posssible problems.</Note>
Adding or subtracting units of any item to the cart, or even new items, changes the amount. The transaction on the Cash App Afterpay side now has a different amount than the amount in the merchant's Shopify shop.

According to Shopify, payments apps must not do any of the following:

* Use any [Shopify APIs](https://shopify.dev/api) other than the Payment Apps API and [mandatory webhooks](https://shopify.dev/docs/apps/webhooks/configuration/mandatory-webhooks) for General Data Protection Regulation (GDPR)

* For more details, see the [Prohibited actions](https://shopify.dev/docs/apps/payments#prohibited-actions) section

If the amount is different and the customer has paid less than the order at the Shopify shop, the order status automatically becomes **Partially Paid**.

![faq-9.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/faq-9.png)

#### Fix the problem

You, the merchant, must make a manual action to fix the problem. Here are some ideas:

* If the amount paid is less than the final order value, you can ask the customer to submit an extra payment. Ask the customer to use a different payment method to make this payment

* If the amount paid is more than the final order value, you can make a partial refund to resolve the discrepancy

* You can cancel the entire order, and refund the customer. Then ask the customer to place their order again, this time with the correct number of items in the cart

## <Note>If this problem occurs regularly, please inform Shopify.</Note>

## Messaging

### Selectively hide Cash App Afterpay Messaging

Shopify sellers manually placing the [Onsite Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started) widget on their **Product Detail** and **Cart** pages can selectively hide the **Onsite Messaging Widget** for certain items.

Tag products you want to exclude (for example, `no-cash-app-afterpay`) and insert a brief code snippet into your theme files where the `<square-placement>` tags are located.

<Note>This option is ideal for Shopify merchants who prefer to restrict the usage of Cash App Afterpay for specific products, including gift cards.</Note>
**Product Detail page**

```js
{% unless product.tags contains 'no-cash-app-afterpay' %}
<square-placement>
</square-placement>
{% endunless %}
```

**Cart page**

```js
{% assign cash_app_afterpay_eligible = true %}
{% for item in cart.items %}
{% if item.product.tags contains 'no-cash-app-afterpay' %}
{% assign cash_app_afterpay_eligible = false %}
{% break %}
{% endif %}
{% endfor %}
{% if cash_app_afterpay_eligible %}
<square-placement>
</square-placement>
{% endif %}
```

***

## Onsite Messaging App

### How do I get started with Cash App Afterpay On-Site Messaging for Shopify?

To use the Cash App Afterpay On-Site Messaging app, you must install the app from the [Shopify app store](https://apps.shopify.com/afterpay-messaging). Configure this app according to your preferences. This setup includes customizing the appearance of on-site messages and ensuring the messages integrate with your store's theme.

***

### How can I manually add Cash App Afterpay messaging to my Shopify theme?

You can manually integrate Cash App Afterpay messaging into your Shopify theme. This process involves adjusting your theme's HTML/Liquid files to include Cash App Afterpay's messaging scripts at the desired locations on your product and cart pages. For details see the [Manually Add Cash App Afterpay Site Messaging to Theme](/cash-app-afterpay/guides/platforms/shopify/manually-add-cash-app-afterpay-site-messaging-to-theme) page.

***

### What are the implementation steps for Cash App Afterpay On-Site Messaging on Shopify?

There are several key steps to implement:

* Ensure your store meets the technical requirements

* Configure the app's settings in your Shopify admin

* Test the messaging display on your store to confirm that it functions correctly and reflects the intended customer experience.

For details on all the above steps, see the [Cash App Afterpay On Site Messaging App](/cash-app-afterpay/guides/platforms/shopify/cash-app-afterpay-on-site-messaging-app) page.

***

## Cash App Pay

### Generate Cash App Pay Logo URL on Shopify

As part of the Cash App Pay checkout setup process, you need to provide Cash App Afterpay with a logo URL. This is for a Cash App Pay logo that appears on the checkout page.

Sometimes it's hard to figure out what this logo URL will be, so here's a method:

1. Go to [Shopify admin](https://accounts.shopify.com/lookup?) and log in as normal.

2. Go to the *Files* page.

   ![cash-app-logo-workaround.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cash-app-logo-workaround.png)

3. Upload a square shaped logo that is at least 256 x 256 pixels in size and under 2MB file size. For the full Cash App logo specification, see the [Adding Cash App Pay to Your Site](/cash-app-afterpay/guides/api-development/add-cash-app-pay-to-your-site/overview#add-your-logo-to-the-qr-code-scanner) page. Any square shaped logo that meets the size criteria will do, the logo does not have to be the Cash App logo.

4. Give Caash App Afterpay the URL to the logo.

---

# Stripe

<Info title="Migrate from Afterpay to Cash App Afterpay">
  If you are an Afterpay merchant, see the 

  [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/stripe-migration)

   for information on the migration from Afterpay to Cash App Afterpay.
</Info>

## Integration Process

To add Cash App Afterpay as a Payment Method to your site please contact your Stripe Account Manager.

## Integration Documentation

[Learn how to accept Cash App Afterpay payments through Stripe](https://stripe.com/docs/payments/afterpay-clearpay)

### Cash App Afterpay Messaging and Best Practice Guidelines

See the [Stripe Site Messaging](https://docs.stripe.com/payments/payment-method-messaging) page to add simple messaging to your site.

See also our [On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started) pages to make the most of Cash App Afterpay on your site.

---

# WIX

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/wix-migration) for information on the migration from Afterpay to Cash App Afterpay.</Info>
To integrate Cash App Afterpay with WIX, follow the instructions below.

## Install and configure Cash App Afterpay

<Note>
  Before you begin, make sure you have a registered Cash App Afterpay account.
</Note>

1. Log in to the [Wix Website Admin Portal](https://users.wix.com/signin?forceRender=true). The *My sites* page appears.

2. Select the site you want, normally this is the name of your store.

3. From the left side menu, select **Settings**. The **Settings** page appears.

   ![wix-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wix-1.png)

4. Click **Accept payments**, the **Accept Payments** page appears.

   ![wix-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wix-2.png)

5. Look at the top-right of the screen. There is a **Your business location:** field. This should be the region you registered for Cash App Afterpay. If it shows the wrong region, click the down chevron and select the correct region.

6. At the bottom of the page, click **See More Payment Options**, the **More Payment Options** page appears. Scroll down the page to find **Afterpay**.

7. Click **Connect**, the *Connect Afterpay* page appears. Follow the instructions on the page. You must enter the **Merchant ID** and **Secret Key** that we have given you.

   ![wix-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wix-3.png)

8. Click **Connect**. Cash App Afterpay has now been added as a payment method. Your Payment Methods page should now include Cash App Afterpay. Your customers can now use Cash App Afterpay to buy goods or services from you.

<Warning title="Do not enable Sandbox mode">
  Only use Sandbox mode when instructed by a Cash App Afterpay account manager or other technical expert.
</Warning>

## Supported countries and regional settings

Cash App Afterpay is available for domestic purchases, using local currency, in the USA only.

To change your settings:

1. Log-in to Wix and go to the **Settings** menu, just like step 3 in the procedure above.

2. Click **Language & region**, the **Language & Region** page appears.

   ![wix-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wix-4.png)

3. Make the changes you want.

4. Click the **Save** button in the top right corner of the page.

To check your regional settings, log in to Wix and navigate to **Settings** > **General Info**  and scroll down to **Regional Settings**

---

# Getting Started

<Info title="Migrate from Afterpay to Cash App Afterpay">If you are an Afterpay merchant, see the [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/platforms/woo-commerce-migration) for information on the migration from Afterpay to Cash App Afterpay.</Info>
Follow the instructions below:

**What are the requirements for the Cash App Afterpay WooCommerce Plugin?**

***

### WordPress Version

The WordPress version must be 4.8.3 or greater to integrate with Cash App Afterpay.

To find the WordPress version number, look at the bottom right corner of the WordPress Admin Dashboard.

### WooCommerce Version

The WooCommerce version must be 3.2.6 or greater to integrate with Cash App Afterpay.

To find the WooCommerce version number:

1. Navigate to **WordPress Admin** > **Plugins** > **Installed Plugins**.

![Getting-started-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Getting-started-1.png)

### Store Currency

Please note that Store Currency must correspond to the Cash App Afterpay account region, which is USA only. To check this:

1. Navigate to: **WordPress Admin** > **WooCommerce** > **Settings** > **General**.

2. Under **Currency options**, the currency must be United States dollar.

   ![Getting-started-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Getting-started-2.png)

[**Express Checkout**](../../EXPRESS-CHECKOUT/What-is-Express-Checkout.md) is available in all supported countries with Version 3.1.0 and above.

## Next Steps

Go ahead and install the Cash App Afterpay plugin; see the [Install Plugin](/cash-app-afterpay/guides/platforms/woo-commerce/install-plugin) page for details.

---

# Install Plugin

**How Can I Install the Cash App Afterpay WooCommerce plugin?**

***

Do the following:

1. Navigate to **WordPress Admin Dashboard**.

2. Navigate to **Plugins** > **Add New**.

   ![woocom-plugin-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woocom-plugin-1.png)

3. Type **Cash App Afterpay** into the Keyword search box:

   ![wooComm-plugin-search.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wooComm-plugin-search.png)

4. Locate the **Cash App Afterpay Gateway for WooCommerce** plugin and click **Install Now**.

   ![wooComm-plugin-install.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wooComm-plugin-install.png)

5. Once the installation is complete, click the **Activate** button.

   ![wooComm-plugin-activate.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wooComm-plugin-activate.png)

## Information for Developers

For developers interested in using the Cash App Afterpay WooCommerce Plugin in local development, click this [link](https://wordpress.org/plugins/afterpay-gateway-for-woocommerce/#developers).

---

# Configure Plugin

**How can I add Cash App Afterpay as a payment method and display Cash App Afterpay Site Messaging?**

***

## Configuration

Complete the steps below to enable and display Cash App Afterpay as a Payment Method, and add Cash App Afterpay messaging to product pages.

<Info>
  If you have completed the Cash App Afterpay Gateway Installation steps, go to Step 3.
</Info>

1. Go to the *WordPress Admin Dashboard*.

2. Go to *Plugins*\* > *Installed Plugins*.

3. Find the *Cash App Afterpay Gateway for WooCommerce* in the plugin list and click the **Settings** button.

   ![woo-config-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-config-1.png)

4. Go to the *Core Configuration* section.

   ![woo-config-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-config-2.png)

5. Enter the Merchant ID provided by Cash App Afterpay into the *Merchant ID* field.

   ![woo-config-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-config-3.png)

6. Enter the Secret Key provided by Cash App Afterpay into the *Secret Key* field.

   ![woo-config-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-config-4.png)

7. Click the **Save changes** button at the bottom of the page.

<Info>After a successful save of the Cash App Afterpay credentials, the *Merchant Public ID*, *Minimum Payment Amount*, *Maximum Payment Amount* and *Settlement Currency* values are updated.</Info>
![woo-config-5.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-config-5.png)

<Info>
  The 

  **Sandbox**

   API Environment is only applicable for dedicated test websites. Contact your Cash App Afterpay Account Manager if you need test credentials.
</Info>

## Enable Express Checkout

To enable Express Checkout:

1. Go to **WordPress Admin Dashboard**.

2. Go to **Plugins** > **Installed Plugins**.

3. Find the *Cash App Afterpay Gateway for WooCommerce* in the plugin list and click the **Settings** button.

4. Find *Express Checkout Configuration* and enable the checkbox.

   ![woo-config-6.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-config-6.png)

## Enabling the Cash App Afterpay Messaging for WooCommerce

The Cash App Afterpay messaging can be enabled on:

* Category Pages

* Product Pages

* Cart Page

To start do the following:

1. Login to the Wordpress Dashboard.

2. Go to *Plugins* > *Installed plugins* > *Cash App Afterpay Gateway for Woocommerce* and click *Settings*.

![woo-plugin-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-plugin-1-3.png)

Under *Settings*, you can see settings for:

* [Express Checkout Configuration](#enable-express-checkout)

* [Payment Info on Category Pages](#payment-info-on-category-pages)

* [Payment Info on Individual Product Pages](#payment-info-on-individual-product-pages)

* [Payment Info Display for Product Variant](#payment-info-display-for-product-variant)

These settings are described below.

### Payment Info on Category Pages

![woo-plugin-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-plugin-4-2.png)

To enable the messaging on the Category page, do the following:

1. Ensure the *Enable* checkbox is enabled.

2. Enter the correct hook to position the messaging and set the priority to increase or decrease the height of the Messaging position. See the [Hook](#hook) section below.

#### Hook

The positioning of the Messaging for Woocommerce relies on a hook. [This link](https://www.businessbloomer.com/woocommerce-visual-hook-guide-archiveshopcat-page/) is a guide to understanding hook positioning on Category pages.

<Warning>The hooks for Category pages and Product pages are completely different.</Warning>
For example, use the hook `woocommerce_after_shop_loop_item`to position the messaging under the price:

![woo-plugin-5.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-plugin-5-2.png)

Below is an example of a category page with Cash App Afterpay messaging:

![woo-plugin-6.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-plugin-6-2.png)

<Info>
  For more information on hooks, see the 

  [Hooks](WC-Hooks.mdx)

   page.
</Info>

### Payment Info on Individual Product Pages

To enable the messaging on the individual Product page, do the following:

1. Ensure the Enable checkbox is enabled.

2. Enter the correct hook to position the messaging and set the priority to increase or decrease the height of the Messaging position. See the **Hook** section below.

#### Hook

The positioning of the Messaging for Woocommerce relies on a hook. [This link](https://www.businessbloomer.com/woocommerce-visual-hook-guide-single-product-page/) is a guide to understanding hook positioning for Product pages.

<Warning>The hooks for Category pages and Product pages are completely different.</Warning>
For example, use the hook `woocommerce_before_add_to_cart_form` to position the messaging directly under the Product Page price:

![woo-plugin-8.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-plugin-8-2.png)

Below is an example of a Product Page with Cash App Afterpay messaging:

![woo-plugin-9.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-plugin-9-2.png)

<Info>
  For more information on hooks, see the 

  [Hooks](WC-Hooks.mdx)

   page.
</Info>

### Payment Info Display for Product Variant

This option enables the Cash App Afterpay Messaging for any variant products.

For example, a product that has a price range from between $50 to $200. The Cash App Afterpay Messaging also displays the instalment breakdown according to a price range.

When a customer selects a variant, a specific price appears. This option enables the Cash App Afterpay Messaging to display a specific price breakdown.

---

# Update Plugin

**To update the 'Cash App Afterpay Gateway for WooCommerce' plugin, please follow the below steps.**

***

As updates for the **Cash App Afterpay Gateway for WooCommerce** plugin are released, notifications appear in WordPress Admin.

A number appears in WordPress Admin next to the Plugins link, it shows the number of plugin updates available.

![wc-update-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-1.png)

<Note>
  We strongly recommend that you backup website files and data before you do an update.
</Note>

## Upgrade Instructions

1. Navigate to the **WordPress Admin Dashboard**.

2. Navigate to **Plugins** > **Installed Plugins**.

3. Locate the **Cash App Afterpay Gateway for WooCommerce** in the plugin list.

   > The version update notification is displayed, with links to the release details, and to update the plugin.

4. Click the **update now** link.

   ![wc-update-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-2.png)

5. The **Cash App Afterpay Gateway for WooCommerce** plugin now starts to update.

   ![wc-update-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-3.png)

6. Once complete, the notification bar turns green and the text changes to **Updated!**.

   ![wc-update-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/wc-update-4.png)

---

# Advanced Configuration

This section outlines the advanced configuration options related to the Cash App Afterpay WooCommerce integration and site-specific customisation.

The *Cash App Afterpay Gateway for WooCommerce* plugin is available for extension or customisation, without alterations to the plugin code.

This allows for a greater level of compatibility with future updates.

Advanced Configuration is divided into the following sections:

* [Hooks](#hooks)

* [Shortcodes](#shortcodes)

## Hooks

### Product Eligibility

The Cash App Afterpay plugin runs a series of checks to determine whether Cash App Afterpay should be an available payment option for each individual product. Third-party plugins can exclude Cash App Afterpay from products that would otherwise be considered supported. To fix the exclusion problem, attach the following filter hook:\
`afterpay_is_product_supported`

**Example**

```php
/**
 * @param bool		$bool_result
 * @param WC_Product	$product
 */
function afterpay_ips_callback( $bool_result, $product ) {
	# My custom products don't support Afterpay.
	if ($product->get_type() == 'my-custom-product-type') {
		$bool_result = false;
	}
	return $bool_result;
}
add_filter( 'afterpay_is_product_supported', 'afterpay_ips_callback', 10, 2 );
```

### Customising Hooks & Priorities

Various WooCommerce hooks are assumed to be implemented by the active WordPress theme. Cash App Afterpay methods can be detached from their default hooks and reattached to different hooks, or to the same hooks with different priorities.

Since version 2.1.0, hooks and priorities can be customised from within the plugin settings page.

![hook-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/hook-1.png)

## Shortcodes

This section outlines the shortcodes utilised by the Cash App Afterpay WooCommerce integration.

### Cash App Afterpay Product Logo

This is provided for rendering an advanced `img` tag to display the Cash App Afterpay logo on individual product pages. The `img` tag uses the `srcset` attribute to include 3 different resolutions of the logo for screens with varying pixel density ratios.

```html
[afterpay_product_logo]
```

There are 3 different versions of the logo to chose from:

* `colour`
* `black`
* `white`

The default theme is `colour`. This can be overridden by including a `theme` attribute inside the shortcode. For example, if you have a dark themed website and wish to use the white mono version of the Cash App Afterpay logo:

```html
[afterpay_product_logo theme="white"]
```

### Cash App Afterpay Product Messaging

To use the shortcode on product pages, please make sure the **Payment Info on Individual Product Pages** has been enabled. Edit the text content as appropriate. Optionally, clear the hook name if you would like to disable the default behaviour of rendering the content when the hook is triggered. Instead, the content will then only render wherever the shortcode is added.

![shortcode-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shortcode-1.png)

Then paste `[afterpay_paragraph]` into the product description, or into a content area using your page builder.

![shortcodes-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shortcodes-2.png)

![shortcodes-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shortcodes-3.png)

To use the shortcode on custom pages, provide a product ID in the shortcode:

```html
[afterpay_paragraph id="99"]
```

![shortcodes-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/shortcodes-4.png)

---

# Currency Conversion

Version 3.5.0 and later versions of the Cash App Afterpay plugin for WooCommerce support currency conversion. This is a great feature for merchants who operate in multiple countries with multiple currencies.

## Prerequisites

Before you implement currency conversion, check that:

* You are a merchant enabled for Cross-Border-Trade (CBT) to other countries

* You have a third-party currency conversion plugin. This plugin sends the customer’s selected currency to payment gateways

## Implementation

To implement the currency convertor, do the following:

1. Open **WordPress admin** and navigate to **WooCommerce**.

2. Click **Settings**, and then click the **Payments** tab. The Cash App Afterpay Gateway information appears.

   ![woo-currency-convert-1.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-currency-convert-1.png)

3. Scroll down the page and ensure that these fields contain the correct information:

   * **Enable/Disable**: **Enable Cash App Afterpay** is checked.

   * **Title**: This is what appears as the payment method title on your checkout page. **Cash App Afterpay** is a good default title.

   * **API Environment**: Select **Sandbox** for testing or **Production** for actual use with real customers and real money.

   * **Merchant ID**: Cash App Afterpay gives you the merchant IDs for both Sandbox testing and production use.

   * **Secret Key**: Cash App Afterpay gives you the secret keys for both Sandbox testing and production use.

   * **Minimum Payment Amount**: This is set in your Cash App Afterpay merchant account.

   * **Maximum Payment Amount**: This is set in your Cash App Afterpay merchant account.

   * **Settlement Currency**: This is set in your Cash App Afterpay merchant account.

   * **Merchant Country**: This must be the country where your Cash App Afterpay merchant account is located.

   * **Excluded Categories**: Enter any excluded categories of product or service here and separate each category with a comma. For example, pornography, gambling, firearms, and so on.

   The next section is entitled **Cross Border Trade Configuration**. This section controls the currency conversion.

   ![woo-currency-conversion-2.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-currency-conversion-2.png)

4. Scroll down the page and ensure that these fields contain the correct information:

   * **Enable Multicurrency**: With this enabled, overseas customers are now able to use Cash App Afterpay with their local currency selected and pay the exact amount that they see in checkout

   * With **Enable Multicurrency** disabled, Cash App Afterpay is not available when a foreign currency is selected. However, overseas customers may still be able to log into their local Afterpay/Clearpay customer account to complete the order, and pay in their local currency. This method uses Cash App Afterpay exchange rates (mostly likely different from the rates used on the merchant site). This has always been the default behaviour for cross border trade (CBT) before this multicurrency feature was introduced

   * **CBT Countries**: Cash App Afterpay populates this field, which is a list of countries that have been enabled for CBT. After payment, the currency is converted to your currency for settlement

   * **CBT Limits**: This field shows the exchange rates used. These rates are automatically checked every 15 minutes and updated thens

5. The other fields on this page are not relevant to currency conversion. Scroll down to the bottom of the page and click **Save Changes**.

## The Store Page

Assuming you, the merchant, have applied the correct settings, your store page should behave like this:

* When the customer pays in your local currency, the prices are displayed in your local currency

* When the customer selects their local currency, the prices change to their local currency

See the screenshots below for an example:

![woo-currency-conversion-3.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-currency-conversion-3.png)

In the screenshot above, the store is based in the USA and the customer wants to pay with US dollars. The prices for the items are in US dollars.

![woo-currency-conversion-4.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/woo-currency-conversion-4.png)

In the screenshot above, the customer wants to pay in Australian dollars. The customer clicks the **AUD** button on the right side of the page. The prices automatically change from US dollars to Australian dollars.

---

# Woo Commerce FAQ

**Frequently Asked Questions about the Cash App Afterpay WooCommerce Integration.**

***

## Why is Cash App Afterpay not showing on product pages?

To display the Cash App Afterpay installment detail on the product pages, the active WordPress theme must implement the below action hook:\
`woocommerce_single_product_summary`

<Note>
  You must also enable the *Payment Info on Individual Product Pages*\* setting, and the product must be eligible.

  For advanced configuration, see the **Hooks** section of the [WooCommerce Advanced Configuration](/cash-app-afterpay/guides/platforms/woo-commerce/advanced-configuration) page in this guide.
</Note>

***

## Why is Cash App Afterpay not showing on category and search result pages?

To display the Cash App Afterpay installment detail on the category and search result pages, the active WordPress theme must implement the below action hook:\
`woocommerce_after_shop_loop_item_title`

<Note>
  You must also enable the **Payment Info on Category Pages** setting, and the product/s must be eligible.

  For advanced configuration, see the **Hooks** section of the [WooCommerce Advanced Configuration](/cash-app-afterpay/guides/platforms/woo-commerce/advanced-configuration) page in this guide.
</Note>

***

## Why is Cash App Afterpay not showing on the cart page?

To display the Cash App Afterpay installment detail on the cart page, the active WordPress theme must implement the below action hook:\
`woocommerce_cart_totals_after_order_total`

<Note>
  You must also enable the **Payment Info on Cart Page** setting, and all the cart items must be eligible.

  For advanced configuration, see the **Hooks** section of the [WooCommerce Advanced Configuration](/cash-app-afterpay/guides/platforms/woo-commerce/advanced-configuration) page in this guide.
</Note>

---

# Getting Started with Cash App Afterpay On-Site Messaging

<Info title="Migrate from Afterpay to Cash App Afterpay">
  If you are an Afterpay merchant, see the 

  [Migration page](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay)

   for information on the migration from Afterpay Messaging to Cash App Afterpay Messaging.
</Info>

**What Is Cash App Afterpay messaging?**

***

Cash App Afterpay Messaging informs your customers - as they browse - that pay by installments with Cash App Afterpay is available. This helps to improve your conversion rates and average order value.

The Cash App Afterpay Messaging Widget takes all the following actions:

* Automatically displays the most optimal payment option. If you have the Pay Monthly product, the widget displays monthly installment messaging for higher priced items and Pay-in-4 (installments) messaging for lower priced items

* Calculates and displays the installment amount

* Displays the Cash App Afterpay Information Modal when a customer clicks on the ⓘ (information) icon.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Small-backpack.png" alt="small-backpack.png" />

<Info title="Using Cash App Afterpay Messaging assets ensures">
  * You meet Cash App Afterpay's compliance criteria: You can always be sure you are using the latest terms of service; you are up-to-date with the latest regulatory information and brand identity. You will display the correct product and fee information
  * You maximize the benefits of Cash App Afterpay. Our best practice recommendations are tried, tested, and proven to optimize your checkout funnel
</Info>

## See Also

* [Implementation](/cash-app-afterpay/guides/afterpay-messaging/implementation)

* [Placement](/cash-app-afterpay/guides/afterpay-messaging/placement)

* [Upgrade to On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/migration)

---

# On-Site Placement

**Where do I place the Cash App Afterpay messaging on my site?**

***

We recommend that you add Cash App Afterpay Messaging to your product, cart, and payment pages.

Product and cart page visibility ensures customers are aware of Cash App Afterpay before they reach the checkout page.

The easiest way to present Cash App Afterpay as a payment option to your customers is to use the Cash App Afterpay On-Site Messaging.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/product-page-messaging.png" alt="product-page-messaging.png" noZoom />

Above - Product page messaging.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/cart-page-messaging.png" alt="cart-page-messaging.png" noZoom />

Above - Cart page messaging.

---

# Implementation

## Messaging installation

On-Site Messaging adds pay-over-time messaging to your store's website. For example, in the picture below the messaging is:

*4 payments of \$25.00 with Cash App Afterpay*
*Learn more*

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Product page messaging-2.png" alt="Product page messaging.png" noZoom />

Updates to the messaging are automatic, and a specific set of messaging logic is designed for your products (Pay in 4, Pay Monthly, etc). Use our On-Site Messaging Editor in the Business Hub to customize, preview, and manage your messaging.

## Requirements

To use this On-site Messaging feature you must:

* Be an existing Cash App Afterpay merchant
* Have a direct integration with Cash App Afterpay
* Have at least one retail website live and ready for use; a Sandbox environment is also available for testing

<Note>
  If you already have Cash App Afterpay Messaging through the JavaScript library, we recommend you replace these with On-Site Messaging instead. See the 

  [Migration page](/cash-app-afterpay/guides/afterpay-messaging/migration)

   for details.
</Note>

## Business hub environments

On-site Messaging configurations are environment-specific and tied to your production and sandbox merchant accounts. See our page on [Business Hub Access](/cash-app-afterpay/guides/welcome/business-hub) or speak to your dedicated account manager if you need assistance getting user access to the Business Hub links below.

| Environment | Link                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| Sandbox     | [https://hub.us-sandbox.afterpay.com/onsite-messaging](https://hub.us-sandbox.afterpay.com/onsite-messaging) |
| Production  | [https://hub.us.afterpay.com/onsite-messaging](https://hub.us.afterpay.com/onsite-messaging)                 |

## Sandbox testing

We recommend that you start by configuring On-Site Messaging in the [Sandbox Business Hub](https://hub.us-sandbox.afterpay.com) to review the Cash App Afterpay messaging on your development store before you go live in production.

To test, you need access to the Sandbox Business Hub.

Before deploying to production, ensure that:

* Messaging appears correctly on all product pages
* Messaging updates when price changes
* Messaging appears correctly on cart page
* Multiple products in cart show correct total installment amount
* Ineligible products/carts correctly hide messaging
* Messaging is responsive on mobile devices
* All required attributes are properly populated

When you are satisfied with your testing, you're ready to go to the production [Business Hub](https://hub.us.afterpay.com) to configure your messaging. From this portal, you can configure Cash App Afterpay messaging for the live site.

## On-Site Messaging quickstart guide

### Configure On-Site Messaging

Start by accessing either environment's Business Hub:

* [Sandbox](https://hub.us-sandbox.afterpay.com) — we recommend that you start here
* [Production](https://hub.us.afterpay.com)

1. Once logged in, navigate to the On-Site Messaging tab in the sidebar
   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/OSM implementation 1.png" alt="OSM implementation 1.png" noZoom />

2. From the On-Site Messaging tab, go to the Placements sub-page
   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/OSM implementation 2.png" alt="OSM implementation 2.png" noZoom />

3. Select the Product or Cart page to customize your messaging from the options available. You can make adjustments to the logo, text size, and theme by placement.
   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/OSM implementation 3.png" alt="OSM implementation 3.png" noZoom />

4. Navigate to the Settings sub-page to find additional advanced configuration options.
   <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/OSM implementation 4.png" alt="OSM implementation 4.png" noZoom />

5. Once your configuration settings are ready, click the Implementation Guide sub-page and follow the instructions there to add the messaging to your associated environment storefront in three steps.

Here's an example from the production On-Site Messaging tab:

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/OSM implementation 5.png" alt="OSM implementation 5.png" noZoom />

### Add On-Site Messaging to your storefront

To display installment messaging on your storefront, add the respective `<square-placement>` tag from the Implementation Guide to the product page and cart page files in your codebase. Place the messaging immediately below the price element of the product and the total element of the cart.

Example square placement on product page:

```javascript
<square-placement
  data-mpid="{Replace with your MPID}"
  data-placement-id="{Replace with your product Placement ID}"
  data-page-type="product"
  data-amount="{Replace with your own price variable}"
  data-currency="{Replace with your own currency variable}"
  data-consumer-locale="{Replace with consumer locale variable}"
  data-item-skus="{Replace with SKU variable}"
  data-item-categories="{Replace with category variable}"
  data-is-eligible="true"
>
</square-placement>
```

Make sure to correctly configure the following dynamic properties for each `<square-placement>` tag added on your site:

1. Set the `data-amount` with the amount that appears on the page to calculate the installments. Keep the `data-mpid` and `data-placement-id` attributes in place with their current values unchanged.

2. Set the `data-currency` to the customer's currency and `data-consumer-locale` to the customer's country.

3. Set `data-item-skus` to any unique product identifier you use, provided as a string. If you have multiple products in the cart, separate them with a comma.

4. Set `data-item-categories` as one or more category names for the relevant product. This is provided as a string or for multiple categories, separate them with a comma.

5. To restrict a product from sale with Cash App Afterpay, set the `data-is-eligible` attribute to false. To restrict a cart from sale with Cash App Afterpay, set the `data-cart-is-eligible` attribute to false. This is optional.

---

# Migration

We support two messaging products:

* On-Site Messaging is our latest messaging product
* JavaScript Library V1 is our legacy messaging product

We recommend that you update to the On-Site Messaging product. Follow this guide to learn how.

## Migrate from the JavaScript Library V1 to On-Site Messaging

You have two migration choices:

* Self-migration: Your IT team does the migration

* Assisted migration: Afterpay helps you do some parts of the migration

## Self-migration

Depending on how customized your implementation is, follow one of these two paths.

### Light customizations

If you've made minor customizations to the Afterpay JavaScript attributes, do the following:

1. Find the `<afterpay-placement>` element you currently have. Copy it and paste it somewhere you can refer back to. This gives you a list of configuration changes you've made.

   <Note>
     For example, in:
     `<afterpay-placement data-is-eligible="true" data-locale="en_US" data-currency="USD" data-amount="59" data-show-upper-limit="false" data-size="xs" data-logo-type="lockup" data-lockup-theme="black"></afterpay-placement>`

     The configuration changes could include:

     * `data-show-upper-limit="false"`
     * `data-size="xs"`
     * `data-logo-type="lockup"`
     * `data-lockup-theme="black"`
   </Note>

2. Delete the old script: `<script src="https://js.afterpay.com/afterpay-1.x.js" async></script>`

3. Find and remove all instances of the elements below from the code:

   * `afterpay-placement`

   * `Afterpay.createPlacements`

   * `new Afterpay.AfterpayPlacement()`

   * `Afterpay.launchModal`

   * `afterpay-price-table`

4. Follow the instructions to [add On-Site Messaging to your website](/cash-app-afterpay/guides/afterpay-messaging/implementation#add-on-site-messaging-to-your-storefront).

5. Make attribute changes if needed. Click **Save all changes**.

### Major customizations

If you've made larger customizations to the custom Cascading Style Sheet (CSS) and the JavaScript, do the following:

1. Log in to the Business Hub to install On-Site Messaging.

2. Follow the steps in the [Implementation guide](/cash-app-afterpay/guides/afterpay-messaging/implementation).

3. Go to the Implementation Guide page and find the `<data-mpid>` and `<data-placement-id>` for each placement (both Product and Cart).

4. Go to your codebase, add your MPID to each placement as a `data-mpid` attribute.

5. Add your placement IDs to each placement as `data-placement-id` attributes.

6. Return to the messaging tool and make attribute changes if needed. Click **Save all changes**.

### Migrate from the dynamic widget to On-Site Messaging

The widget isn't actively supported by Afterpay; we strongly recommend migrating to On-Site Messaging. If you already have an agreement to use the widget, you can wait until this agreement expires.

To remove the widget:

1. Find the previous code and note the inline customisations that have been made.

2. Remove script from head section:

   `<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>`

3. Remove the previous code:

   `<div id="afterpay-messaging-widget"></div>`

4. Follow the On-Site Messaging implementation instructions.

---

# Older Messaging Information

## New Merchants

We recommend that all new merchants use our current [On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started) product.

## Existing Cash App Afterpay Merchants

We currently support two messaging products.

[On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started) is our current messaging product, and our previous product is messaging from the [JavaScript Library](/cash-app-afterpay/guides/afterpay-messaging/older-messaging-information-and-links).

If you want to migrate from the JavaScript Library messaging to the current On-Site messaging product, see the information on the [Upgrade to On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/migration) page.

### Transition from Afterpay to Cash App Afterpay

**On-Site Messaging**

If you use On-Site Messaging, it will be updated automatically.

**JavaScript Library**

If you use the JavaScript library for your messaging, it will be updated automatically.

## JavaScript Library Messaging

You can find links to our previous messaging products and features, including the JavaScript library here.

<Warning>
  The products and features listed here are only partially supported. All Cash App Afterpay merchants with a direct integration should use On-Site Messaging for on-site messaging. See 

  [Getting Started with On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started)

   and 

  [Upgrade to On-Site Messaging](/cash-app-afterpay/guides/afterpay-messaging/migration)

   for more details.
</Warning>

## Links

### JavaScript Library

* [JavaScript Library introduction](JavaScript-Library.mdx)

* [Style Messaging](Style-Messaging.mdx)

* [Advanced Usage](Advanced-Usage.mdx)

* [Pay Monthly Enhanced Javascript Library Features](Pay-Monthly-enhanced-JavaScript-library-features.mdx)

* [Afterpay.js Reference](Afterpay-js-Reference.mdx)

---

# Launch Cash App Afterpay Info Modal Anywhere

This page is a short guide on how to use JavaScript to enable any element to open the Cash App Afterpay information modal.

For the customer, it should be a single click operation; click on any element and the Cash App Afterpay information modal opens.

## Instructions

Do the following:

1. Open your existing messaging script with an HTML editor.

2. Load `square-marketplace.js` script in the HTML, see the example below:

   ```html
   <script src="https://js.squarecdn.com/square-marketplace.js" async></script>
   ```

3. Add `data-afterpay-modal` attribute to any element. When a customer clicks that element, it now opens the Cash App Afterpay information modal. Here's an example code snippet that opens when a customer clicks the icon symbol:

   ```html
   <div>
     Or 4 interest-free payments with 
     <strong>[Cash App Afterpay Logo] <span data-afterpay-modal>ⓘ</span></strong>
   </div>
   ```

### Regional Modal Themes

| Region        | Accepted Values                |
| ------------- | ------------------------------ |
| United States | "en\_US", "en\_US-theme-white" |

For example:

`<strong>[Cash App Afterpay Logo] <span data-afterpay-modal="en_US">ⓘ</span></strong>`

Results in a modal suitable for US merchants.

---

# API Quickstart

## Prerequisites

Before you get started, make sure that you have:

* Signed up for a merchant account at get.afterpay.com
* Received sandbox credentials from Cash App Afterpay

Cash App Afterpay is available to merchants with businesses in the United States. For businesses in Canada, Australia, and New Zealand, see [Afterpay](https://developers.afterpay.com/docs/api/welcome/getting-started). For UK businesses, see [Clearpay](https://developers.clearpay.co.uk/clearpay-online/docs/getting-started-with-clearpay-online).

## Basic API calls

### Get Configuration (/v2/configuration)

The [Get Configuration](/cash-app-afterpay/api-reference/reference/configuration/get-configuration) endpoint retrieves your Afterpay order limits. We recommend regularly calling this endpoint as part of a scheduled background process and storing the `minimumAmount` and `maximumAmount` values on your server.

### Create Checkout (/v2/checkouts)

The [Create Checkout](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) endpoint creates a new checkout and returns an order token. When you call the Create Checkout endpoint, you give Cash App Afterpay order details, customer information, and the URL to direct customers to after checkout. Cash App Afterpay responds with a token used to identify the checkout. Use this token to direct the customer to the Cash App Afterpay checkout flow.

### Capture Full Payment (/v2/payments/capture)

To capture the full order value immediately, call the [Capture Full Payment](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment) endpoint. Calling this endpoint completes payment approval, starts the customer's payment plan, and settles the full order to your bank account. When you call this endpoint, you provide the order token and receive a payment object.

### Authorize Payment (/v2/payments/auth)

This is the first endpoint to call when you use the deferred payment flow. To authorize the full payment amount up front and collect funds later, start by calling the [Authorize Payment](/cash-app-afterpay/api-reference/reference/payments/auth) endpoint. Calling this endpoint completes payment approval for a certain amount. When you call this endpoint, you provide the order token and receive a payment object.

### Capture Authorized Payment (/v2/payments/\{orderId}/capture)

This is the second endpoint to call when you use the deferred payment flow. After the payment is authorized, call the [Capture Payment](/cash-app-afterpay/api-reference/reference/payments/capture-payment) endpoint to capture a full or partial payment. When you call this endpoint, you provide a unique request ID and the amount you want to capture (up to the authorized amount) and you receive an updated payment object.

### Create Refund (/v2/payments/\{orderId}/refund)

Call the [Create Refund](/cash-app-afterpay/api-reference/reference/payments/create-refund) endpoint to issue a full or partial refund. When you call this endpoint, you provide a unique request ID and the amount you want to refund (up to the captured amount) and you receive a refund object.

## Post-requisites

While you set up and test your integration, you can view all sandbox orders in the [Business Hub](/cash-app-afterpay/guides/welcome/business-hub).

After you set up your API integration, contact Cash App Afterpay to complete certification testing and receive your live credentials. Once you're given live credentials, you can launch Cash App Afterpay on your website.

---

# Create a checkout

There are three steps to create a Cash App Afterpay checkout:

1. Call [Get Configuration](/cash-app-afterpay/api-reference/reference/configuration/get-configuration) to retrieve your order limits
2. Call [Create Checkout](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) to generate a checkout token
3. Launch the Cash App Afterpay checkout flow using a redirect or a popup window

| **Action**                                                                                      | **Endpoint**                 | **Purpose**                                          |
| ----------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------- |
| [Get Configuration](/cash-app-afterpay/api-reference/reference/configuration/get-configuration) | `/v2/platform/configuration` | Retrieve Afterpay order limits (min/max values).     |
| [Create Checkout](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1)       | `/v2/checkouts`              | Provide order details and generate a checkout token. |

## Retrieve your order limits

Call the [Get Configuration](/cash-app-afterpay/api-reference/reference/configuration/get-configuration) endpoint to retrieve your minimum and maximum Cash App Afterpay order amounts.

We recommend calling this endpoint once a day as part of a scheduled background process, and storing the `minimumAmount` and `maximumAmount` values on your server.

Use these values to determine:

1. The correct [Cash App Afterpay Messaging](/cash-app-afterpay/guides/afterpay-messaging/getting-started) to show on the Product Detail pages
2. Whether Cash App Afterpay should be presented as an available payment method

A request to create a checkout will be declined if the order grand total is less than the minimum or more than the maximum Cash App Afterpay amount. To change your minimum and maximum order values, contact Cash App Afterpay.

<div>
  ```mermaid
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000',
        'background': '#fff'
      }
    }
  }%%
  sequenceDiagram
      Merchant Website ->> Cash App Afterpay: GET/v2/configuration
      Cash App Afterpay -->> Merchant Website: Configuration
  ```
</div>

## Create a checkout

Call the [Create Checkout](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) endpoint to communicate the order details to Cash App Afterpay. Your request should include:

1. Customer information
2. Order details
3. Order total
4. Shipping details
5. Redirect URLs

<Info>
  Cash App Afterpay uses the order total value to calculate the installment plan and to assist with the customer's pre-approval process.
</Info>

Cash App Afterpay responds with a token used to identify this checkout.
For example, `002.5lmerr3k945d00c7htvcrdff83q36kp10a247m212fjpa5ju`. This token is used to launch the Cash App Afterpay checkout flow using Afterpay.js.

#### Afterpay.js

| **Environment** | **URL**                                           |
| --------------- | ------------------------------------------------- |
| Sandbox         | `https://portal.sandbox.afterpay.com/afterpay.js` |
| Production      | `https://portal.afterpay.com/afterpay.js`         |

<div>
  ```mermaid
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000'
      }
    }
  }%%
  sequenceDiagram
      Merchant Website ->> Cash App Afterpay: POST/v2/checkouts
      Cash App Afterpay -->> Merchant Website: Token
  ```
</div>

## Set up your checkout experience

As part of your integration, decide how customers will complete the Cash App Afterpay checkout flow. There are two options:

* **Redirect method:** Customers are redirected from your website to Cash App Afterpay to complete their payment. At the end of the Cash App Afterpay checkout flow, the customer is redirected back to your website. Most merchants use this method.
* **Popup method:** The Cash App Afterpay checkout flow opens in a popup window on top of your site. For windowed applications, your website is dimmed with a semi-transparent overlay. For full-screen applications (such as mobile interfaces), the flow opens in a new tab. At the end of the Cash App Afterpay checkout flow, the popup closes.

### Implement the redirect method

To use the redirect method, call the following two JavaScript functions, in order:

1. `AfterPay.initialize`: Prepares the Afterpay JavaScript to start the Cash App Afterpay screenflow in the appropriate geographical region.
   * Accepts an object with a required `countryCode` (the two-character ISO 3166-1 country code of the merchant account)
2. `AfterPay.redirect`: Redirects the customer's browser from your website to Cash App Afterpay.
   * Accepts an object with a required `token` (the checkout token returned by the Create Checkout API call)

```js
<html>
<head>
 <script onload="initAfterPay()" src="https://portal.sandbox.afterpay.com/afterpay.js"></script>
</head>
<body>
 <p>Your HTML here</p>
 <script>
 function initAfterPay () {
   AfterPay.initialize({countryCode: "AU"});
   AfterPay.redirect({token: "YOUR_TOKEN"});
 }
 </script>
</body>
</html>
```

If the customer successfully completes the checkout flow, they’re returned to your `redirectConfirmUrl` with a checkout token and a `SUCCESS` status appended as HTTP query parameters: `www.merchant-example.com/confirm?&status=SUCCESS&orderToken=002.5lmerr3k945d00c7htvcrdff83q36kp10a247m212fjpa5ju`

If the customer cancels the checkout, they’re returned to your `redirectCancelUrl` with a checkout token and a `CANCELLED` status appended as HTTP query parameters: `www.merchant-example.com/confirm?&status=CANCELLED&orderToken=002.5lmerr3k945d00c7htvcrdff83q36kp10a247m212fjpa5ju`

<Info title="Recommendation">
  Try using your Sandbox merchant credentials to get a token from [Create Checkout](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1). Use this token to test the Cash App  Afterpay screenflow on JSFiddle: [https://jsfiddle.net/afterpay/cyd3pxfj/](https://jsfiddle.net/afterpay/cyd3pxfj/)

  <br /><br />Note that the login and redirect features won't work, because JSFiddle loads the Cash App Afterpay screenflow inside a frameset.
</Info>

### Implement the popup method

To use the popup method, call the following JavaScript functions, in order:

1. `AfterPay.initialize`: Prepares the Afterpay JavaScript to start the Cash App Afterpay screenflow in the appropriate geographical region.
2. `AfterPay.open`: Opens the Cash App Afterpay popup window, launching the checkout flow for the customer.
3. `AfterPay.onComplete`: Defines a callback function. It checks whether the customer successfully completes the checkout flow and handles successful payments and cancellations.
4. `AfterPay.transfer`: Sends the checkout token to Cash App Afterpay, finalizing the payment process.

When a customer’s payment is complete, Cash App Afterpay uses `postMessage` to call a JavaScript method on your front end system.

<Note>
  The popup method doesn't redirect customers to the `redirectConfirmUrl` or `redirectCancelUrl`, but these fields are still required for the Create Checkout call. These fields are used for context on `postMessage`.
</Note>

```js
<html>
<head>
 <script type="text/javascript" src="https://portal.sandbox.afterpay.com/afterpay.js"></script>
</head>
<body>
 <button id="afterpay-button">
   Cash App Afterpay it!
 </button>
 <script type="text/javascript">
   document.getElementById("afterpay-button").addEventListener("click", function() {
     AfterPay.initialize({countryCode: "AU"});
     // To avoid triggering browser anti-popup rules, the AfterPay.open()
     // function must be directly called inside the click event listener
     AfterPay.open();
     // If you don't already have a checkout token at this point, you can
     // AJAX to your backend to retrieve one here. The spinning animation
     // will continue until `AfterPay.transfer` is called.
     // If you fail to get a token you can call AfterPay.close()
     AfterPay.onComplete = function(event) {
       if (event.data.status == "SUCCESS") {
         // The customer confirmed the payment schedule.
         // The token is now ready to be captured from your server backend.
       } else {
         // The customer cancelled the payment or closed the popup window.
       }
     }
     AfterPay.transfer({token: "YOUR_TOKEN"});
   });
 </script>
</body>
</html>
```

If the customer successfully completes the checkout flow, Cash App Afterpay calls the `onComplete` method on your website. Cash App Afterpay passes the checkout token and a `SUCCESS` status as properties of a data object. The popup closes.

If the customer cancels the checkout, Cash App Afterpay calls the `onComplete` method on your website. Cash App Afterpay passes the checkout token and a `CANCELLED` status as properties of a data object. The popup closes.

<Note>
  At the end of the checkout flow, if the protocol, host, and port of the opening window don't match those provided in Create Checkout, the customer's browser won't dispatch the JavaScript event for security reasons.
</Note>

**Cash App Afterpay checkout screen**

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/create-a-checkout.png" alt="create-a-checkout.png" noZoom />

---

# Immediate capture

Immediate capture provides a simplified and efficient payment process. It’s ideal for merchants who want to finalize and settle payments immediately upon order confirmation, or who want to minimize complexity. It combines the following actions into a single API call:

* Completing payment approval.
* Starting the customer’s payment plan.
* Settling the full order value into the merchant's bank account.

| **Action**                                                                                       | **Endpoint**           | **Purpose**                                  |
| ------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------- |
| [Capture Full Payment](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment) | `/v2/payments/capture` | Capture order payment and confirm the order. |

## Implement immediate capture

1. [Create a checkout](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout). If the customer confirms their order with Cash App Afterpay, they're returned to your website with an order token and the `SUCCESS` status.
2. Use the order token to call the [Capture Full Payment](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment) endpoint. Once the capture completes, you'll receive a Payment object with a status of `APPROVED` or `DECLINED`.
   * If Cash App Afterpay approves the payment, present the customer with an order confirmation page. The full payment is captured.
   * If Cash App Afterpay declines the payment (for example, if the customer’s credit card details are incorrect), present the customer with suggested corrections or alternative payment methods at checkout.

<div>
  ```mermaid
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000'
      }
    }
  }%%
  sequenceDiagram
      Merchant ->> Cash App Afterpay: Create Order
      Cash App Afterpay -->> Merchant: Token
      Note over Merchant, Cash App Afterpay: Cash App Afterpay checkout flow
      Merchant ->> Cash App Afterpay: Capture
      Cash App Afterpay -->> Merchant: Success
  ```
</div>

### Considerations

* Immediate capture is supported by all platforms.
* You must call the Capture Full Payment endpoint within 180 minutes of receiving the token from the Create Checkout call.
* The Capture Full Payment call is idempotent. It’s safe to retry requests within 24 hours using the same unique requestId.
* Express checkout requires additional data. See [Express Checkout Integration](/cash-app-afterpay/guides/api-development/additional-features/express-checkout) to learn more.

---

# Auth and capture

Deferred capture lets you authorize the full payment amount up front and collect the funds later. The transaction is approved and the customer's payment plan is started. Then, you can capture full or partial payments. If a portion of the order can’t be fulfilled, you can void uncaptured amounts.

This flow is recommended for merchants who ship orders in multiple parts or who charge the full order amount upon delivery.

| **Action**                                                                             | **Endpoint**                     | **Purpose**                                                             |
| -------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------- |
| [Authorize Payment](/cash-app-afterpay/api-reference/reference/payments/auth)          | `/v2/payments/auth`              | Authorize a payment amount for an Afterpay order.                       |
| [Capture Payment](/cash-app-afterpay/api-reference/reference/payments/capture-payment) | `/v2/payments/{orderId}/capture` | Capture full or partial order payments against a payment authorization. |
| [Void](/cash-app-afterpay/api-reference/reference/payments/void-payment)               | `/v2/payments/{orderId}/void`    | Void a full or partial order value and refund the customer.             |

## Implement deferred capture

### Launch checkout and authorize payment

1. [Create a checkout](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout). If the customer confirms their order with Cash App Afterpay, they're returned to your website with an order token and the `SUCCESS` status.
2. Use the order token to call the [Authorize Payment](/cash-app-afterpay/api-reference/reference/payments/auth) endpoint. Once the authorization completes, you'll receive a Payment object with a status of `APPROVED` or `DECLINED`.
   * If Cash App Afterpay authorizes the payment, store the payment `id` and the `expires` value of the `AUTH_APPROVED` payment event. Present the customer with an order confirmation page.
   * If Cash App Afterpay declines the payment (for example, if the customer’s credit card details are incorrect), present the customer with suggested corrections or alternative payment methods at checkout.

### Capture payment

If an order is given `APPROVED` status during the authorization flow, you can now capture the payment. This happens after the customer has seen their order confirmation page and may have left your website.

<Warning title="Important">
  You must capture payment for authorized orders within 13 days. After 13 days, the authorization expires and is automatically voided. At this point, you aren’t able to capture any order value (partial or full). You can’t reopen or update voided transactions; you must call the Checkouts endpoint to create a new order.
</Warning>

#### If you can completely fulfill the order:

Once you determine that the entire order will be fulfilled, call the [Capture Payment](/cash-app-afterpay/api-reference/reference/payments/capture-payment) endpoint with the entire amount.

The capture amount will match both the `originalAmount` and `openToCaptureAmount` for the Payment object, as it was returned in the Auth response.

#### If you can partially fulfill the order:

Once you determine that only part of the order will be fulfilled (for example, if some items are permanently out of stock):

1. Call the [Capture Payment](/cash-app-afterpay/api-reference/reference/payments/capture-payment) endpoint with the amount for all items that will be fulfilled.
2. Call the [Void](/cash-app-afterpay/api-reference/reference/payments/void-payment) endpoint to finalize the order. Refund the `openToCapture` amount to the customer; this will reduce the `openToCapture` amount to zero.

#### If you fulfill the order incrementally:

1. Once a shipment is dispatched, call the [Capture Payment](/cash-app-afterpay/api-reference/reference/payments/capture-payment) endpoint with the amount of all items in the shipment.
2. If you determine that a shipment can't be dispatched, call the [Void](/cash-app-afterpay/api-reference/reference/payments/void-payment) endpoint with the amount of all applicable items.

You can capture or void payments multiple times. Requests that exceed the `openToCapture` amount will fail. Once the `openToCapture` amount equals zero, any further Capture or Void requests will fail.

#### If you can’t fulfill any part of the order:

Once you determine that you can't fulfill any part of the order, call the [Void](/cash-app-afterpay/api-reference/reference/payments/void-payment) endpoint. This refunds the `openToCapture` amount to the customer, reduces the `openToCapture` amount to zero, and finalizes the order.

<Note>
  We don't recommend waiting for the authorization to automatically expire. Even though an approved authorization will automatically be voided after 13 days, the customer begins their payment plan at the time of authorization approval.
</Note>

<div>
  ```mermaid
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000'
      }
    }
  }%%
  sequenceDiagram
      Merchant ->> Cash App Afterpay: Create Order
      Cash App Afterpay -->> Merchant: Token
      Note over Merchant, Cash App Afterpay: Cash App Afterpay checkout flow
      Merchant ->> Cash App Afterpay: Auth
      Cash App Afterpay -->> Merchant: Success
      Note over Merchant, Cash App Afterpay: A period of time passes...
      Merchant ->> Cash App Afterpay: Capture
      Cash App Afterpay -->> Merchant: Success
  ```
</div>

### Considerations

* Deferred capture is supported on the Afterpay v2 API, Salesforce Commerce Cloud, and Adobe Commerce (Magento).
* The minimum capture amount is \$1.00; capture requests below \$1.00 are rejected.
* If an order still has a `paymentState` of `AUTH_APPROVED` or `PARTIALLY_CAPTURED` when the authorization expires, the remaining order amount will automatically be voided.
* The Capture Payment call is idempotent. It’s safe to retry requests using the same unique requestId.

---

# Refunds

| **Action**                                                                         | **Endpoint**                    | **Purpose**                                    |
| ---------------------------------------------------------------------------------- | ------------------------------- | ---------------------------------------------- |
| [Create Refund](/cash-app-afterpay/api-reference/reference/payments/create-refund) | `/v2/payments/{orderId}/refund` | Refunds a full or partial amount for an order. |

Perform a full refund or partial refunds (up to the original order total) based on your refund or cancellation policies. The same Order ID can be used for multiple partial refunds.

Refunds can be used for:

* Full or partial order cancellation
* Returns
* Other scenarios where you want to issue funds back to the customer

### Considerations

* Refunds can't be issued after 120 days from the date of purchase. After 120 days, refund requests are rejected and return a 422 error.
* If using deferred capture, only captured funds can be refunded.
* You can also process refunds from the Cash App Afterpay Business Hub.

---

# Test environments

## Sandbox

Cash App Afterpay provides a sandbox environment for development and testing. Your Cash App Afterpay account manager will provide you with sandbox credentials.

Accounts created within a Cash App Afterpay sandbox only exist within the sandbox. When you make a transaction in the sandbox, no money actually moves.

API calls in the sandbox use the base URL `https://global-api-sandbox.afterpay.com`.

### Sandbox Business Hub

Contact your Cash App Afterpay account manager or delivery manager to request access to the sandbox Business Hub. The sandbox Business Hub provides the same functionality as the production Business Hub.

You can log into the sandbox Business Hub at [https://portal.sandbox.afterpay.com/merchant/](https://portal.sandbox.afterpay.com/merchant/)

You can view all sandbox orders and settlement files, but no settlements are made to your bank account.

### Test customer accounts

You can create test customer accounts in the sandbox environment within your test checkout flow. Each customer account requires a unique email address and phone number.

<Note>
  No SMS messages are sent in the sandbox. Use `111111` as the verification code.
</Note>

### Test credit cards

The sandbox capture response (approved/declined) is determined by the CVV value. Use `000` for approval and `051` for decline.

You can use any dummy Visa or Mastercard number and future expiry date,  as long as it passes a mod 10 check and hasn’t already been used by a different sandbox customer account. You can also use these dummy cards:

| Card Type  | Card Number         | Expiry | CCV | Response |
| ---------- | ------------------- | ------ | --- | -------- |
| Visa       | 4111 1111 1111 1111 | 01/28  | 000 | Approved |
| Visa       | 4111 1111 1111 1111 | 01/28  | 051 | Declined |
| Mastercard | 5215 0977 9282 6659 | 01/28  | 000 | Approved |
| Mastercard | 5215 0977 9282 6659 | 01/28  | 051 | Declined |

### Test Pay Monthly

The Sandbox Pay Monthly Approval response (approved/declined) is determined by the Cart Total value.

| Cart Total Value           | Response                  |
| -------------------------- | ------------------------- |
| $100.00 - $399.99 USD      | 3, 6, or 12 month offers  |
| $400.00 - $3,999.99 USD    | 6, 12, or 24 month offers |
| $4,000.00 - $10,000.00 USD | 6, 12, or 24 month offers |

## Postman collection

You can test the Cash App Afterpay API using Postman, a free-to-download tool for making HTTP requests. To start using Postman, create an account on [postman.com](https://www.postman.com/).

To test the Cash App Afterpay API using postman:

1. Go to the [Afterpay Online API V2](https://www.postman.com/afterpay-1-426879/afterpay-online-apis-v2/overview) public workspace.
2. Fork the collection.
3. Choose a label, workspace, and environment for your fork.
4. Regularly pull the latest changes to update your forked collection.

---

# Certification

After you complete your internal QA testing, you're ready for Cash App Afterpay certification. Contact your Cash App Afterpay account manager to schedule certification testing.

All of your unique production environments are tested. The test suite includes three areas:

* Integration standards

* Customer experience

* Refunds

Certification ensures a great customer experience, minimizes the potential for fraudulent activity, and checks for common technical and compliance issues.

**Your Cash App Afterpay production credentials are issued upon successful completion of certification.**

## Deployment

When moving your integration to your production environment, make sure that you're using the production API endpoint and JavaScript URL.

| Environment | API Endpoint                                                                                                                                                         | Screenflow (Javascript)                                                                            |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Sandbox     | [https://api.us-sandbox.afterpay.com/v1](https://api.us-sandbox.afterpay.com/v1) OR [https://api.us-sandbox.afterpay.com/v2](https://api.us-sandbox.afterpay.com/v2) | [https://portal.sandbox.afterpay.com/afterpay.js](https://portal.sandbox.afterpay.com/afterpay.js) |
| Production  | [https://api.us.afterpay.com/v1](https://api.us.afterpay.com/v1) OR [https://api.us.afterpay.com/v2](https://api.us.afterpay.com/v2)                                 | [https://portal.afterpay.com/afterpay.js](https://portal.afterpay.com/afterpay.js)                 |

<Info title="Update the User-Agent Header">
  When you move to a production environment, make sure the User-Agent Header is updated with the production Merchant ID.
</Info>

---

# Disputes

## Overview

Customers can raise and manage disputes related to non-delivery of goods directly through the Afterpay Customer Portal. Merchants can manage and respond to these disputes via the Disputes API and the Afterpay Business Hub. If a resolution can't be reached, Afterpay can step in to adjudicate.

<Info>
  At this time, Cash App Afterpay supports only 

  `product_not_received`

   as a dispute reason.
</Info>

## Dispute lifecycle

1. A customer raises a dispute through their Cash App Afterpay dashboard or app and provides evidence to support their case.

2. Cash App Afterpay notifies the merchant using methods including email, the Business Hub, API, and webhooks.

3. The merchant responds to the dispute. They can accept the dispute (which closes the dispute in the customer's favor) or contest the dispute by providing evidence via the API or the Business Hub.

4. If the merchant provides evidence, the dispute is returned to the customer.  The customer can either accept the merchant’s decision (which closes the dispute in the merchant's favor) or can reject the merchant’s evidence.

5. If the customer rejects the merchant's evidence, an Afterpay agent steps in. The agent decides the outcome of the dispute based on the available evidence. Both parties are notified of the decision.

### **Merchant Side Dispute Lifecycle Diagram**

<div>
  ```mermaid
  ---
  config:
    layout: dagre
  ---
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000'
      }
    }
  }%%
  flowchart TD
      id1(("start")) --> id2(["Needs Merchant Response"])
      id2 -- Merchant Challenge --> id3(["Under Review"])
      id2 -- Merchant Accept --> id6(["Merchant Lost"])
      id3 -- Consumer Accept --> id5(["Merchant Won"])
      id3 -- Consumer Reject --> id4(["$AP Adjudication"])
      id4 -- Merchant Favor --> id5
      id4 -- Consumer Favor --> id6
      id5:::termState
      id6:::termState
  ```
</div>

## Dispute windows

Cash App Afterpay updates dispute statuses and sends dispute notifications according to the following time frames:

| Window                         | Description                                                                                                                                        | Time frame |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| Dispute open                   | The maximum window of time (from the transaction date) for a dispute to be opened. 60 days after the statement date, dispute claims may be denied. | 120 days   |
| Merchant’s evidence submission | The allowed time between the merchant being notified of a dispute and the final time for evidence submission.                                      | 13 days    |
| Cash App Afterpay’s decision   | The allowed time from the moment of evidence submission to Cash App Afterpay’s final decision.                                                     | 30 days    |

## Dispute statuses

Cash App Afterpay supports the following dispute statuses:

| Status              | Description                                                                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `needs_response`    | Cash App Afterpay has created the dispute and notified the merchant, but the merchant has not taken action.                                              |
| `under_review`      | Merchant has submitted evidence to Cash App Afterpay, and it is currently under review.                                                                  |
| `won`               | The evidence submitted is accepted by Cash App Afterpay and the dispute is won by the merchant. Note that this is a terminal state.                      |
| `lost`              | The evidence submitted is rejected by Cash App Afterpay and the dispute is lost by the merchant. Note that this is a terminal state.                     |
| `merchant_refunded` | Merchant has issued a refund. If the refund is equal to or greater than the dispute amount, then this is a terminal state.                               |
| `merchant_voided`   | Merchant has canceled all or a portion of the order. If the voided amount is equal to or greater than the dispute amount, then this is a terminal state. |

## Closing reasons

A closing reason indicating how the final decision on the dispute was reached is displayed to the merchant. The following closing reasons are accepted:

| Merchant-facing Closing Reason | Description                                                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `merchant_accepted`            | Merchant accepted the dispute.                                                                                                      |
| `evidence_accepted`            | Merchant submitted evidence which was accepted. The dispute was closed in the merchant’s favor.                                     |
| `evidence_rejected`            | Merchant submitted the evidence but it was rejected and the dispute was closed in the customer’s favor.                             |
| `deadline_expired`             | Merchant failed to submit evidence for the dispute and the submission window timed out. Dispute was closed in the customer's favor. |
| `customer_cancelled`           | Customer withdrew the dispute and therefore it was closed in the merchant’s favor.                                                  |

<Info>
  All dispute records are saved in the Cash App Afterpay system and are accessible through the Dispute APIs; dispute records are not deleted.

  In financial reporting, there will be a separate record for a dispute. Order ID, Dispute ID, financial changes (+/-) are included in the record. Afterpay only gathers funds from the merchant after the merchant loses the dispute.
</Info>

---

# Integrate with the Disputes API

Merchants can integrate directly with the Disputes API to scale their disputes process and integrate with other order management and customer service tools. This is helpful for merchants who handle a high volume of transactions.

| **Action**                                                                                   | **Endpoint**                       | **Purpose**                               |
| -------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------- |
| [Receive dispute](/cash-app-afterpay/api-reference/reference/disputes/receive-dispute)       | GET `/v2/disputes/{dispute_id}`    | Get detailed information about a dispute. |
| [List disputes](/cash-app-afterpay/api-reference/reference/disputes/retrieve-dispute)        | `/v2/disputes`                     | List disputes based on a set of criteria. |
| [Accept dispute](/cash-app-afterpay/api-reference/reference/disputes/accept-dispute)         | `/v2/disputes/{dispute_id}/accept` | Accept a dispute case.                    |
| [Respond to dispute](/cash-app-afterpay/api-reference/reference/disputes/respond-to-dispute) | POST `/v2/disputes/{dispute_id}`   | Submit evidence to respond to a dispute.  |
| [Upload file](/cash-app-afterpay/api-reference/reference/disputes/upload-file)               | `/v2/disputes/files`               | Upload a file for a dispute.              |
| [Retrieve file](/cash-app-afterpay/api-reference/reference/disputes/retrieve-file)           | `/v2/disputes/files/{id}`          | Retrieve a file for a dispute.            |

<div>
  ```mermaid
  ---
  config:
    sequence:
      mirrorActors: true
      width: 300
  ---
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000'
      }
    }
  }%%
  sequenceDiagram
      participant AP as $Afterpay Dispute API
      participant M as Merchant
      rect rgb(250,250,250)
        note over AP: Event: Dispute created
        AP -->> M: Webhook Notification
        M ->> AP: Fetch Dispute API
        AP ->> M: Latest Dispute Object
        M ->> M: Create Dispute
      end
      rect rgb(250,250,250)
        note over AP: Event: Dispute updated
        AP -->> M: Webhook Notification
        M ->> AP: Fetch Dispute API
        AP ->> M: Latest Dispute Object
        M ->> M: Update Dispute Status
      end
      rect rgb(250,250,250)
        note over AP: Action: Merchant Challenge Dispute
        M ->> AP: Upload File Api
        AP ->> M: Return file token
        M ->> AP: Challenge Dispute API
        AP ->> M: Latest Dispute Object
        M ->> M: Update Dispute Status
      end
      rect rgb(250,250,250)
        note over AP: Action: Merchant Accept Dispute
        M ->> AP: Accept Dispute API
        AP ->> M: Latest Dispute Object
        M ->> M: Update Dispute Status
      end
  ```
</div>

## Dispute notifications

Cash App Afterpay notifies merchants using webhooks when a dispute is created and any time it is updated. Cash App Afterpay expects the ACK (acknowledgement) with a 200 response. If the acknowledgement fails, Cash App Afterpay will reattempt sending the webhook a few times with exponential backoff.

The following table outlines the content for the webhook call:

| Field name           | Data type | Description                                                                                                        |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `webhook_event_id`   | String    | The `event_id` of the webhook.                                                                                     |
| `webhook_event_type` | String    | An enum variable that indicates if the dispute was created or updated. Possible values are `created` and `updated` |
| `dispute_id`         | String    | Dispute Identifier.                                                                                                |
| `merchant_reference` | String    | Merchant identifier.                                                                                               |

A `dispute_id` is passed in the webhook call. Merchants can use the Get Dispute endpoint to get the details for the dispute.

### Notification setup

Merchants must provide a webhook URL and merchant IDs to the Cash App Afterpay merchant service/dispute team to get the HMAC key and enable the notification.

The webhook endpoint should be maintained by merchants or partners, it should allow POST requests with `content-type` = `application/json`.

<Note>
  The payload format is defined in the previous table.
</Note>

### Notification authentication

* (option 1) Key Exchange Wiki: [Diffie-Hellman Key Exchange via Openssl: Quick Guide](/cash-app-afterpay/guides/api-development/disputes/integrate-with-the-disputes-api#key-exchange)
* (option 2) Securely get HMAC key from [https://squareup.sendsafely.com/](https://squareup.sendsafely.com/)

### HMAC signature

Cash App Afterpay recommends that you use HMAC for the authentication of the webhook notification.
Consider the following structure of the raw HTTP message.

```javascript
POST ${notification_uri} HTTP/1.1
Host: ${notification_base_url}
X-Afterpay-Request-Date: 1664239810
X-Afterpay-Request-Signature: ${signature}
Content-Type: application/json
{
    "webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe",
    "webhook_event_type": "created",
    "dispute_id": "dp_KvGaECApCMdsH8earUSa2V",
    "merchant_reference": "08CF65ZSFNHVM"
}
```

There will be two extra fields for authentication.

* `X-Afterpay-Request-Date` records the send time for the webhook request. We recommned aborting the stale notification after a fixed time (if you receive the webhook and current timestamp - `${X-Afterpay-Request-Date}` is greater than 5 minutes).
* `X-Afterpay-Request-Signature` records the signature of the HMAC key. Typically we generate the signature using the following steps:

  ```javascript
  PAYLOAD={"webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe", "webhook_event_type":       "created", "dispute_id": "dp_KvGaECApCMdsH8earUSa2V", "merchant_reference": "08CF65ZSFNHVM"}
  URL= "${partner_notification_uri}"
  SECRET=<hmac secret key here>
  TIME=1664239810
  MESSAGE="$URL\n$TIME\n$PAYLOAD"
  X-Afterpay-Request-Signature=$(printf "${MESSAGE}" | openssl dgst -hmac ${SECRET} -sha256   -binary | base64)
  ```

When a merchant or merchant agency receives a webhook notification, we recommend generating verification signatures in following steps.

<Info>
  If `HMAC == X-Afterpay-Request-Signature`, then continue to process the notification, or the merchant should abort the request.
</Info>

```javascript
PAYLOAD={"webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe", "webhook_event_type": "created", "dispute_id": "dp_KvGaECApCMdsH8earUSa2V", "merchant_reference": "08CF65ZSFNHVM"}
URL= "${Notification_uri}"
SECRET=<hmac secret key here>
TIME=${X-Afterpay-Request-Date}
MESSAGE="$URL\n$TIME\n$PAYLOAD"
HMAC=$(printf "${MESSAGE}" | openssl dgst -hmac ${SECRET} -sha256 -binary | base64)
```

## Series of events

| Trigger                                        | API event                                                                                                                                                                                                                                     | Outcome                                                                                                              |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| The customer creates a dispute in the app      | Webhook notifies the merchant (incl. webhook\_event\_type = created and a dispute\_id)                                                                                                                                                        | The dispute is created and the merchant is notified. The dispute status is updated to `needs_response`.              |
| The merchant retrieves the dispute information | The Get Dispute endpoint is called to fetch status of the dispute (based on Dispute ID), and returns the updated Dispute object. If images or attachments were supplied; these are retrieved with the Retrieve File api endpoint.             | The merchant can challenge or accept the dispute.                                                                    |
| The merchant challenges the dispute            | The merchant collates their response collateral internally. If there are files to upload, the Upload File endpoint is called for the relevant files. The Respond to Dispute endpoint is called which references the file IDs for those files. | The merchant has submitted evidence to challenge the dispute. The dispute status is updated to `under_review`.       |
| The merchant accepts the dispute               | The Accept Dispute endpoint is called, returns the Dispute object to the merchant.                                                                                                                                                            | The dispute status is updated to `lost` and the dispute is closed. The closing reason is set to `merchant_accepted`. |
| The customer accepts the merchant’s evidence   | If webhook is enabled, this will come through as a notification                                                                                                                                                                               | The dispute status is updated to ‘won’ and the dispute is closed. The closing reason is set to `evidence_accepted`.  |
| The customer rejects the merchant’s evidence   |                                                                                                                                                                                                                                               | The dispute is sent to Afterpay for adjudication                                                                     |
| Afterpay adjudicates in the merchant’s favor   | If webhook is enabled, this will come through as a notification                                                                                                                                                                               | The dispute status is updated to ‘won’ and the dispute is closed. The closing reason is set to `evidence_accepted`.  |
| Afterpay adjudicates in the customer’s favor   | If webhook is enabled, this will come through as a notification                                                                                                                                                                               | The dispute status is updated to `lost` and the dispute is closed. The closing reason is set to `evidence_rejected`. |
| The customer cancels the dispute               | If webhook is enabled, this will come through as a notification                                                                                                                                                                               | The dispute status is updated to `won` and the dispute is closed. The closing reason is set to `customer_cancelled`. |
| The customer updates the dispute.              | Webhook notifies merchant (incl. webhook\_event\_type = updated and a dispute\_id) Get Dispute endpoint is called to fetch status of the dispute (based on Dispute ID), returns the updated Dispute object.                                   | The dispute status is updated. The dispute status is updated to `needs_response`.                                    |

---

# Manage disputes in the Business Hub

Merchants can manage disputes via the Cash App Afterpay Business Hub, which provides centralized tools for dispute handling and reconciliation. In the Business Hub, merchants can:

* View and filter open disputes
* Accept and challenge disputes
* Submit supporting documentation without contacting Cash App Afterpay customer service
* Export settlement, disputes, and reconciliation reports
* Customize email notification settings for disputes

This allows merchants to save time managing disputes, improve internal coordination and transparency, and reduce unnecessary conversations with Cash App Afterpay.

Customers can open, manage, and track disputes directly from the Cash App Afterpay customer portal. They can accept and reject a merchant’s response, and cancel a dispute if they receive their order.

## Merchant experience

1. Merchant receives an email notification that a new dispute has been opened.

2. Merchant can view the new dispute, and all other open disputes, in the Cash App Afterpay Business Hub.

3. Clicking on “Review Detail” next to each dispute displays more information about the dispute.

4. Merchant can accept the dispute, challenge it, or notify Cash App Afterpay that a refund has already been issued.

5. When a merchant challenges a dispute, they add supporting documentation, which is included in the response back to the customer.

6. If a merchant accepts, or does not respond within 13 days, to a dispute, Cash App Afterpay refunds the customer and initiates a reversal with the merchant.

7. If there is no resolution between the customer and merchant, Cash App Afterpay adjudicates the dispute and rule in either party’s favor based on the available evidence.

8. Merchant receives confirmation of dispute outcome in the Business Hub.

## Customer experience

1. A customer selects the relevant order in the customer portal and clicks “Goods Not Received.” Customers may only raise a dispute 7 days after the payment is captured. After 120 days, they can no longer raise a dispute.

2. The customer is prompted to contact the merchant directly before submitting a dispute through Cash App Afterpay.

3. The customer submits information about the dispute, confirms the dispute amount, and is invited to submit evidence along with the dispute ticket.

4. A pop-up, as well as an email notification, is sent to confirm receipt of the dispute.

5. The dispute is sent to the merchant, and customers can monitor progress through the Cash App Afterpay Customer Portal.

6. Once the merchant has replied, customers can accept or reject the merchant’s decision, or cancel the dispute if their order arrives.

## Cash App Afterpay's role

If a dispute decision is rejected by the customer, Cash App Afterpay can:

* Adjudicate disputes that remain unresolved between merchants and customers
* Debit settlement funds from unresponsive and at-fault merchants to refund customers for non-delivery of goods

---

# Webhook Signature Generation

A webhook signature is a cryptographic hash used to verify the authenticity and integrity of webhook requests. It ensures that the request comes from a trusted source and has not been tampered with.

Cash App Afterpay uses webhooks to [notify merchants and partners about disputes](/cash-app-afterpay/guides/api-development/disputes/integrate-with-the-disputes-api).

Webhooks need a signature for security and verification purposes. Webhook signatures help:

* Prevent spoofing – They ensure only trusted sources can send webhooks
* Detect tampering – If the payload is altered, the signature will not match
* Add security – The signature works as an additional layer of protection alongside HTTPS.

## Pre-work

Before you can receive and act on webhooks, you need to do the following:

1. Set up a webhook endpoint and an associated URL. The endpoint must allow POST requests with content-type = application/json.
2. Contact Afterpay merchant support and give them the following information:
   * The URL you set up for webhook notification in step 1
   * Your unique partner ID

After we receive this information, we share an HMAC (Hash Message Authentication Code) value with you and enable our systems for notification.

<Note>
  Don't confuse the HMAC shared secret key with the HMAC value that is generated using the HMAC shared secret key.
</Note>

## Verify the webhook event payload

To verify a webhook event payload with the HMAC value, follow these steps:

1. **Retrieve the webhook event signature:**
   * Retrieve the event signature from the `X-Afterpay-Request-Signature` header provided in the webhook.
2. **Construct raw signature in canonical form:**
   * `url`: The destination URL for the webhook
   * `time`: The `X-Afterpay-Request-Date` header value, represented as a UNIX timestamp
   * `payload`: The raw JSON body of the webhook
   * Concatenate raw signature with format: `${url}\n${time}\n${payload}`
3. **Generate HMAC-SHA-256 value:**
   * Create HMAC value using the raw signature and the API secret corresponding to API key utilities to create the webhook
   * Use a constant-time cryptographic library to generate the signature to prevent timing attacks
4. **Compare the generated signature with the received signature:**
   * Compare the computed signature against the `X-Afterpay-Request-Signature` header value
   * If both signatures match, then the request is verified as legitimate
   * If they don't match, reject the request

### Code sample:

```js
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

// Secret provided by Afterpay team.
const SECRET = "WEBHOOK_URL_SECRET" 

function verifyWebhookSignature(req) {

// Step 1: Retrieve the webhook event signature
 const receivedSignature = req.headers['x-afterpay-request-signature'];

 // Step 2: Construct the message
 const url = req.headers['host'];
 const time = req.headers['x-afterpay-request-date'];
 const payload = req.rawBody;
 const message = `${url}\n${time}\n${payload}`

 // Step 3: Create HMAC SHA-256 value.
 const expectedSignature = crypto.createHmac('sha256', SECRET)
 .update(message)
 .digest('base64');

 // Step 4: Assert recieved signature with expected signature.
 const receivedBuffer = Buffer.from(receivedSignature, 'hex');
 const expectedBuffer = Buffer.from(expectedSignature, 'hex');
 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
}

app.post('/afterpay', (req, res) => {
 console.log("Message received:", req.body);
 if (!verifyWebhookSignature(req)) {
     return res.status(403).send("Invalid signature");
 }

 console.log("✅ Webhook verified:", req.body);
 res.status(200).send("Webhook received");
});

app.listen(80, () => {
 console.log('Webhook server listening on port 80');
});
```

## Manual signature verification

You can verify the webhook signature manually using the command line. This can be helpful for debugging or verifying payloads without using a backend server.

```bash
PAYLOAD='{"webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe", "webhook_event_type": "created", "dispute_id": "dp_KvGaECApCMdsH8earUSa2V", "merchant_reference": "08CF65ZSFNHVM"}'
URL="${notification_uri}" # replace with your webhook endpoint URL
SECRET=<your_hmac_secret_key> # replace with the HMAC secret key shared by Afterpay
TIME=1741100821 # UNIX timestamp from X-Afterpay-Request-Date header

MESSAGE="$URL\n$TIME\n$PAYLOAD"
HMAC=$(printf "${MESSAGE}" | openssl dgst -hmac "${SECRET}" -sha256 -binary | base64)
```

The resulting `HMAC` value is the signature you should compare against the value in the `X-Afterpay-Request-Signature` header.

**Sample request:**

```http
POST ${notification_uri} HTTP/1.1
Host: ${notification_base_url}
X-Afterpay-Request-Date: 1664239810
X-Afterpay-Request-Signature: ${HMAC}
Content-Type: application/json

{
  "webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe",
  "webhook_event_type": "created",
  "dispute_id": "dp_KvGaECApCMdsH8earUSa2V",
  "merchant_reference": "08CF65ZSFNHVM"
}
```

---

# Introduction to express checkout

Cash App Afterpay express checkout reduces the overall checkout steps on desktop and mobile so that your shoppers can complete their orders quickly.

Customers can check out directly from the shopping cart or product page, using their pre-filled Cash App Afterpay account information (name, shipping address, phone number, email) to complete their orders on your website.

Simply put, there are fewer checkout steps, leading to higher conversion.

## Express checkout vs standard checkout

### Standard checkout flow

With standard checkout, the customer proceeds through the checkout process as normal, selecting Cash App Afterpay as a payment option in your payments section.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Checkout Flow - Standard.png" alt="Checkout Flow - Standard.png" noZoom />

### Express checkout flow

With express checkout, the customer can choose to ‘buy now with Cash App Afterpay’ on a product page, or shop for multiple items and choose to ‘checkout with Cash App Afterpay’ from the cart.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Checkout Flow - Express.png" alt="Checkout Flow - Express.png" noZoom />

There are two ways to implement express checkout:

#### Integrated shipping

Customers select delivery options inside the Cash App Afterpay checkout flow. The order is completed within Cash App Afterpay checkout.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Integrated Shipping.png" alt="Integrated Shipping.png" noZoom />

#### Deferred shipping

The customer returns to your website's checkout to select delivery options and complete their order.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Deferred Shipping.png" alt="Deferred Shipping.png" noZoom />

### Which one is right for you?

| Integrated Shipping                                           | Deferred Shipping                                               |   |
| ------------------------------------------------------------- | --------------------------------------------------------------- | - |
| Less than 5 shipping options                                  | 5 or more shipping options                                      |   |
| Simple shipping options (e.g. single option for whole order)  | Complex shipping options (e.g. individual options at SKU level) |   |
| Simple tiered shipping options (e.g. standard, express, rush) | Customized shipping options (e.g., timeslot booking)            |   |
| Click and collect pickup selection before checkout entry      | Third party click and collect pickup                            |   |

---

# Set up express checkout with integrated shipping

Express checkout uses the same APIs as standard checkout. Integrated shipping enhances the experience by embedding your shipping options directly into Afterpay express checkout, streamlining the process. When paired with the Buy Now flag, it creates a one-step checkout.

To set it up:

1. Generate a Cash App Afterpay [order token](#generate-an-afterpay-order-token) to start the express checkout process
2. Create an express checkout [button](#create-an-express-checkout-button) to load the checkout window
3. Create the [checkout](#create-checkout) using Afterpay.js
4. Capture [payment](#capture-payment) to finalize the order

<Warning>
  When using integrated shipping, you must launch the checkout in a popup. The redirect method isn't supported.
</Warning>

## Generate an Afterpay order token

Before launching Cash App Afterpay express checkout, create an order token by calling the [Create Checkout](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) endpoint. This lets you specify the order amount, items, and other details.

The backend call is triggered when the express checkout button is clicked. A new token is required for each order. If you store the token in a database, be sure to support arbitrary string length and content, as a token’s format can change.

For express checkout orders, there are two key differences from standard checkout:

* Set `mode` to `express`
* Use a single `popupOriginUrl` instead of `redirectConfirmUrl` and `redirectCancelUrl`

```curl
curl --request POST \
  --url https://api-sandbox.Afterpay.com/v2/checkouts \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant": {"popupOriginUrl": "https://example.com"}}'
```

## Create an express checkout button

When a customer clicks this button on a cart or product page, it launches Cash App Afterpay checkout in a popup.

1. Add a standard HTML `<button>` element wherever you want it to appear on your website.
2. Assign a unique ID (for example, `Afterpay-express-button`). This allows you to have multiple buttons on the same page.
3. Set the entry point using the `data-Afterpay-entry-point` attribute. Allowed values are:
   * `product-page`
   * `mini-cart`
   * `cart`
4. Set the button label using the `data-Afterpay-checkout-button-label` attribute. This identifies the button for analytics or tracking purposes.

```html
<button id="Afterpay-express-button"
        data-Afterpay-entry-point="mini-cart"
        data-Afterpay-checkout-button-label="Check out using Cash App Afterpay">
  Check out using Cash App Afterpay
</button>
```

### Button options

Multiple button styles are available, each clearly communicating the next step to the customer.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Types - All in one.png" alt="Button Types - All in one.png" noZoom />

<Info>
  Integration assets are available 

  [here](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets)

  , or contact your Cash App Afterpay merchant services representative.
</Info>

## Create checkout

### Load Afterpay.js

Add the Afterpay.js script to your website. Set the `onload` attribute to point to a custom function that will initialize the popup (for example, `initAfterpay`).

```js
<script src="https://portal.sandbox.Afterpay.com/Afterpay.js? async onload="initAfterpay()">
  </script>
```

### Initialize the popup window

Define your `initAfterpay()` function before loading the script. This function uses `Afterpay.initializeForPopup()` to configure the express checkout behavior. Configure the following properties:

* `countryCode`: Your merchant account's two-character ISO 3166-1 code
* `addressMode`: One of the provided address mode constants
* `target`: The ID or class of the button that triggers checkout
* Set the `buyNow` flag to `true`. This shows customers a "Buy Now" button for one-step checkout.
* Handle lifecycle events:
  * `onCommenceCheckout`: Retrieve the Afterpay token from your server, then call `actions.resolve(TOKEN)` to start checkout.
  * `onComplete`: See [Finalize the Order](#finalize-the-order) for details.
  * `onShippingAddressChange`: See [Listen for Address Changes](#listen-for-address-changes) for details.

```html
<html>
  <head>
    <script>
      // ensure this function is defined before loading Afterpay.js
      function initAfterpay () {
        Afterpay.initializeForPopup({
          countryCode: 'AU',
          onCommenceCheckout: function (actions) {
            /* retrieve Afterpay token from your server */
            /* then call `actions.resolve(token)` */
          },
          onComplete: function (data) {
            /* handle success/failure of checkout */
          },
          target: '#Afterpay-express-button',
          addressMode: Afterpay.ADDRESS_MODES.ADDRESS_WITH_SHIPPING_OPTIONS,
          buyNow: true,
        })
      }
    </script>
    <script src="https://portal.sandbox.Afterpay.com/Afterpay.js? async onload="initAfterpay()">
    </script>
  </head>
  <body>
    <button id="Afterpay-express-button" 
    data-Afterpay-entry-point="mini-cart">
    data-Afterpay-checkout-button-label="Checkout using Afterpay Express">
      Checkout using Afterpay Express
    </button>
  </body>
</html>
```

#### Address mode

To support different shipping types in the checkout, configure the `addressMode` property using one of the provided constants in the format `Afterpay.ADDRESS_MODES.<NAME>`, where `<NAME>` is one of the following:

| Constant                                         | Description                                                                                                                                                                                        |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **With Shipping Options**                        |                                                                                                                                                                                                    |
| `ADDRESS_WITH_SHIPPING_OPTIONS`                  | Displays checkout with the option for the customer to configure their shipping address and be able to select from the merchant's list of available shipping options.                               |
| `SHIP_TO_ORDER_ADDRESS`                          | Displays checkout with the chosen customer shipping address and be able to select from the merchant's list of available shipping options. See preselected shipping address order for more details. |
| `PICKUP_FROM_ORDER_ADDRESS`                      | Displays checkout with the chosen merchant pickup address for the order. See pickup orders for more details.                                                                                       |
| **Without Shipping Options**                     |                                                                                                                                                                                                    |
| `ADDRESS_WITHOUT_SHIPPING_OPTIONS`               | Displays checkout with the option for the customer to configure their shipping address only.                                                                                                       |
| `SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS` | Displays checkout with the option for the customer to configure their shipping address only with the intention to continue their order back on the merchant.                                       |
| `NO_ADDRESS`                                     | Displays checkout with the option for the customer to configure their shipping address only with the intention to buy now.                                                                         |

<Note>
  If `addressMode` isn't specified, `ADDRESS_WITH_SHIPPING_OPTIONS` is used by default.
</Note>

### Customer completes checkout

When the customer clicks the Cash App Afterpay checkout button, a popup opens. The customer is prompted to log in and review their order details. They can select a payment method, delivery address, and shipping option.

After confirming their order, the popup closes and the customer returns to your site. Checkout completion is communicated via the `onComplete` callback.

## Finalize the order

When the customer completes Cash App Afterpay express checkout, the `onComplete` Javascript function is called. It receives an `event` argument with a `data` field containing the following properties:

| **Property**        | **Type**          | **Description**                                          |
| ------------------- | ----------------- | -------------------------------------------------------- |
| `status`            | string            | The order status: `"SUCCESS"` or `"CANCEL"`              |
| `orderToken`        | string            | The order token provided when initializing the checkout. |
| `merchantReference` | string (optional) | The merchant’s ID or reference number for the order.     |
| `orderInfo`         | object (optional) | The order info (if available) from the checkout.         |

**orderInfo data properties**

| **Property**      | **Type**   | **Description**                                                                                                         |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `shippingAddress` | `Contact`  | The shipping address for the order.                                                                                     |
| `shippingOption`  | object     | Contains `shippingOptionIdentifier`, indicating the ID of the user’s chosen shipping option (integrated shipping only). |
| `consumer`        | `Consumer` | Contains the user’s `givenNames`, `surname`, and `email`. `phoneNumber` isn't defined here.                             |

```js
Afterpay.initializeForPopup({
  // ...
  onComplete: function (event) {
    if (event.data.status == "SUCCESS") {
      // The consumer has confirmed the payment schedule.
      // Call your server here to retrieve the order details.
    } else {
      // The consumer cancelled the payment or closed the popup window.
    }
  },
});
```

### Get order details

Retrieve the transaction details by calling the [Get Checkout](/cash-app-afterpay/api-reference/reference/checkouts/get-checkout) endpoint. This is the source of truth for the order. It includes the user's name, email address, delivery address, phone number, and order total.

Verify the order details to ensure that the shipping address, `shippingOptionIdentifier`, and resulting amount are valid and match your records.

### Capture payment

Capture payment using the [immediate payment flow](/cash-app-afterpay/guides/api-development/api-quickstart/immediate-capture). For express checkout, the payload must include an `amount` field.

Once payment is captured, the express checkout order is complete.

<Note>
  For Cross Border Trade orders, ensure that the currency is consistent throughout the entire checkout flow.

  For example, if  you're a UK merchant displaying a 100 GBP order in AUD for an Australian consumer on your site. For example, if you initiate checkout by sending us the order amount in GBP, then at capture the final order amount must also be in GBP.
</Note>

### Listen for address changes

The `onShippingAddressChange` callback lets you dynamically update shipping options and taxes based on the consumer’s shipping address. It receives two arguments: `data` (the address) and `actions` (callback functions).

Afterpay calls `onShippingAddressChange` when the customer first enters the Cash App Afterpay summary page, and again whenever they update their shipping address. During these calls, you should:

* Use the address details in `data` to determine supported shipping options (e.g. by contacting your backend API).
* Use `actions.resolve` to return the options to the Afterpay express checkout, or
* Use `actions.reject` to signal any errors, providing an appropriate shipping constant

#### Data argument

| Property      | Type   | Description                                                                                      |
| ------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `name`        | String | Full name of the consumer                                                                        |
| `address1`    | String | First line of the address.                                                                       |
| `address2`    | String | Second line of the address                                                                       |
| `area2`       | String | Village/local area of the address                                                                |
| `suburb`      | String | Suburb/City of the address                                                                       |
| `state`       | String | AU: State<br />NZ: Region<br />UK: County<br />US: State<br />CA: Province or Territory          |
| `postcode`    | String | ZIP or postal code. If the country does not have postcodes, the countryCode will be sent instead |
| `countryCode` | String | The ISO 3166-1 alpha-2 country code.                                                             |
| `phoneNumber` | String | The phone number, in E.123 format.                                                               |

#### Actions argument

| Property  | Type     | Description                                                                                                                                                                                                                                     |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolve` | Function | Call this method to provide the shipping options applicable to the consumer’s address. Takes an array of Shipping Option objects.                                                                                                               |
| `reject`  | Function | Call this method when you are unable to handle the request. Do not throw an error, instead call this method with a Shipping Constant as the first argument to indicate a status, e.g. `actions.reject(Afterpay.CONSTANTS.SHIPPING_UNSUPPORTED)` |

#### Shipping options model

| Attribute        | Type              | Description                                                  |
| ---------------- | ----------------- | ------------------------------------------------------------ |
| `id`             | String (required) | A shipping option identifier. Max length 128.                |
| `name`           | String (required) | The name of the shipping option.                             |
| `shippingAmount` | Money (required)  | The shipping amount (without tax, if including taxAmount).   |
| `taxAmount`      | Money (optional)  | The tax amount.                                              |
| `orderAmount`    | Money (required)  | The total amount for the order including shipping and taxes. |
| `description`    | String            | A description for this shipping option.                      |

#### Retrieve shipping options via API

```js
Afterpay.initializeForPopup({
  // ...
  onShippingAddressChange: function (data, actions) {
    fetch('/your-shipping-endpoint', {
      method: 'POST',
      headers: { 'content-Type': 'application/json' },
      body: JSON.stringify(data),
    }).then(function(options) {
      actions.resolve(options)
    }).catch(function(error) {
      // Parse the response and send a Afterpay rejection, e.g.:
      actions.reject(Afterpay.CONSTANTS.SHIPPING_UNSUPPORTED)
    })
  },
})
```

#### Calculate shipping options in Afterpay.js

```js
Afterpay.initializeForPopup({
  // ...
  onShippingAddressChange: function (data, actions) {
    if (data.countryCode !== 'AU') {
      // Reject any unsupported shipping addresses
      actions.reject(Afterpay.CONSTANTS.SHIPPING_UNSUPPORTED)
    } else {
      // Calc shipping inline
      actions.resolve([ {
        id: '1', name: 'Standard', description: '3 - 5 days',
        shippingAmount: { amount: '0.00', currency: 'AUD'},
        taxAmount: { amount: '3.18', currency: 'AUD'},
        orderAmount: { amount: '34.99', currency: 'AUD'},
      }, {
        id: '2', name: 'Priority', description: 'Next business day',
        shippingAmount: { amount: '10.99', currency: 'AUD'},
        taxAmount: { amount: '4.28', currency: 'AUD'},
        orderAmount: { amount: '47.08', currency: 'AUD'},
      } ])
    }
  },
})
```

#### Shipping constants

To indicate error scenarios, call `actions.reject()` with the appropriate constant. The constants are in the form `Afterpay.CONSTANTS.<NAME>`, where `<NAME>` is one of the following:

| **Constant**                    | **Description**                              |
| ------------------------------- | -------------------------------------------- |
| `SHIPPING_ADDRESS_UNRECOGNIZED` | Unrecognized address.                        |
| `SHIPPING_ADDRESS_UNSUPPORTED`  | Recognized address, but will not ship there. |
| `SERVICE_UNAVAILABLE`           | General service error.                       |

<Note>
  Express checkout doesn't perform any calculations. Your web app is responsible for calculating the correct total, including taxes and shipping, for each shipping option.
</Note>

### Optional callbacks

#### Listen for shipping option changes

The `onShippingOptionChange` callback is optional, allowing you to track the customer's chosen shipping option as it changes. It will be called with a single Shipping Option argument each time the customer selects a shipping option.

```js
Afterpay.initializeForPopup({
  // ...
  onShippingOptionChange: function (data) {
    console.log(data)
  },
})
```

If you need to modify the shipping option amounts after the user has selected a shipping option, use `onShippingOptionChange` with an additional action argument to update the checkout. When `onShippingOptionChange` is triggered:

1. Use the shipping option data to perform the required modification (for example, recalculate the tax via your backend API).

2. Once updated, use `actions.resolve` to return an object containing:
   * `id`: The same shipping option id from `onShippingOptionChange`
   * `shippingAmount`: The updated shipping amount for the selected option
   * `taxAmount`: The updated tax amount for the selected option
   * `orderAmount`: The updated order amount for the selected shipping option

3. Use `actions.reject` to signal any errors.

```js
Afterpay.initializeForPopup({
  // ...
  onShippingOptionChange: function (data, action) {
      fetch('/your-update-shipping-option-endpoint', {
          method: 'POST',
          headers: { 'content-Type': 'application/json' },
          body: JSON.stringify(data),
      }).then(function(options) {
          actions.resolve({
             id: data.id, 
             shippingAmount: { amount: '0.00', currency: 'AUD'},
             taxAmount: { amount: '3.18', currency: 'AUD'},
             orderAmount: { amount: '34.99', currency: 'AUD'},
          })
      }).catch(function(error) {
          // Parse the response and send the error, e.g.:
          actions.reject(error)
      })
  },
})
```

### Listen for error messages

To facilitate handling of log/warning/error messages, you can optionally replace `Afterpay.onMessage` with a custom function. It receives the following payload:

| Property   | Type   | Description                                     |
| ---------- | ------ | ----------------------------------------------- |
| `severity` | String | One of: `log`, `warning`, or `error`            |
| `message`  | String | The message (normally displayed on the console) |

```js
Afterpay.onMessage = function (payload) {
  console[payload.severity](payload.message)
}
```

## Optional features

### Target multiple checkout buttons

If you have multiple checkout buttons on the same page, these can be targeted by adding a common class to each of these buttons:

```html
<button class="Afterpay-express-button”>
  Button 1 - Checkout using Afterpay Express
</button>
<button class="Afterpay-express-button”>
  Button 2 - Checkout using Afterpay Express
</button>
```

Then, set the target in the Afterpay.js initialize function with the common class. For example, set target in `initializeForPopup`:

```js
Afterpay.initializeForPopup({
  // ...
  target: ".Afterpay-express-button",
});
```

### Pickup orders

To support pickup orders using integrated shipping, follow these steps:

1. Allow customers to select pickup options (e.g. pickup location and date) that impact shipping costs **before** launching express checkout.
2. When a customer selects pickup, use the pickup address in the `shipping` body parameter when creating the order.
3. When calling `initializeForPopup`, set `addressMode` to `Afterpay.ADDRESS_MODES.PICKUP_FROM_ORDER_ADDRESS`.
   ```js
   Afterpay.initializeForPopup({
     // ...
     addressMode: Afterpay.ADDRESS_MODES.PICKUP_FROM_ORDER_ADDRESS,
   })
   ```
4. Configure `onShippingAddressChange` to return the name and description of the pickup selection. This typically means returning a single option, for example:
   ```js
   actions.resolve([ {
     id: 'pickup-store-123', name: 'Click & Collect',
     description: 'Available for next-day pickup',
     shippingAmount: { amount: '0.00', currency: 'AUD'},
     taxAmount: { amount: '3.18', currency: 'AUD'},
     orderAmount: { amount: '34.99', currency: 'AUD'},
   } ])

   ```
5. Optionally, you can collect additional pickup information (for example, an alternate pickup person) on your order review page.

<Tip>
  If `initializeForPopup` is called before you know whether a customer has selected pickup, you can safely call `initializeForPopup` again. Each call overwrites the previous calls.
</Tip>

### Preselect shipping option

If customers can choose a shipping option on your site before launching express checkout, you can send us this information when checkout launches.

1. Set the `shippingOptionIdentifier` in the body parameter when creating the order. This preselects the option if it's returned from `onShippingAddressChange` when checkout loads.
2. Set `addressMode` in `Afterpay.initializeForPopup()` to define how the shipping address is handled.
   * To provide a list of shipping options, use `Afterpay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS`
   * To **not** provide a list of shipping options, use `Afterpay.ADDRESS_MODES.SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS`
3. Include the shipping address in the `shipping` parameter when creating the order.

```curl
curl --request POST \
 --url https://api-sandbox.afterpay.com/v2/checkouts \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant": {"popupOriginUrl": "https://example.com"}, "shipping": {"name": "Your Store Name", "line1": "123 Store Address", "postcode": "0000"}, shippingOptionIdentifier: “standard”
}}'
```

## Errors

The following errors can occur during Cash App Afterpay express checkout with integrated shipping:

| **Error**                                                             | **How to Proceed**                                                                                                                                                               |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Uncaught ReferenceError: Afterpay is not defined`                    | Ensure that `Afterpay.js` is being loaded on your page before referencing it, e.g. by using the `onload` script attribute.                                                       |
| `Uncaught ReferenceError: initAfterpay is not defined`                | Ensure that `initAfterpay` is defined **before** the script tag that loads `Afterpay.js`.                                                                                        |
| Afterpay popup opens but doesn't launch a checkout                    | Ensure your `onCommenceCheckout` handler has no errors (check the console), and that it calls `actions.resolve` with a valid token.                                              |
| `onComplete` callback is not called when checkout finishes            | This can occur due to issues with `postMessage` communication, especially with in-app browsers. Contact Cash App Afterpay with steps to replicate the issue.                     |
| `onShippingAddressChange` is not being called on address changes      | Ensure that `popupOriginUrl` was correctly defined when creating the checkout token.                                                                                             |
| Afterpay checkout does not display shipping options from the merchant | Ensure your `onShippingAddressChange` handler calls `actions.resolve` with a valid list of shipping options.                                                                     |
| The shipping address is invalid or ineligible for shipping            | Use `actions.reject` with a valid Shipping Constant to signal your rejection of the address to Afterpay.                                                                         |
| There are missing fields on the provided address                      | `onShippingAddressChange` sends a reduced address payload with only the data needed to calculate shipping. Full address details should be retrieved after the checkout finishes. |

---

# Set up express checkout with deferred shipping

Express checkout uses the same APIs as standard checkout. To set it up:

1. Generate an Afterpay [order token](#generate-an-afterpay-order-token) to set up the express checkout process
2. Create an express checkout [button](#create-an-express-checkout-button) to load the checkout window
3. Create the [checkout](#create-checkout) using Afterpay.js
4. Continue the [checkout process](#continue-the-checkout-process) on your website
5. Show and update the payment schedule using the [checkout widget](/cash-app-afterpay/guides/api-development/additional-features/checkout-widget)
6. Capture [payment](#capture-payment) to finalize the order

## Generate an Afterpay order token

Before launching Cash App Afterpay express checkout, create an order token by calling the Create Checkout endpoint. This lets you specify the order amount, items, and other details.

The backend call is triggered when the express checkout button is clicked. A new token is required for each order. If you store the token in a database, be sure to support arbitrary string length and content, as a token’s format can change.

For express checkout orders, there are two key differences from standard checkout:

* Set `mode` to `express`
* Optionally, use a single `popupOriginUrl` instead of `redirectConfirmUrl` and `redirectCancelUrl`. With deferred shipping, you can also use a [redirect](#use-a-redirect-flow).

```curl
curl --request POST \
  --url https://api-sandbox.Afterpay.com/v2/checkouts \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant": {"popupOriginUrl": "https://example.com"}}'
```

## Create an express checkout button

When a customer clicks this button on a cart or product page, it launches Cash App Afterpay checkout in a popup.

1. Add a standard HTML `<button>` element wherever you want it to appear on your website.
2. Assign a unique ID (for example, `Afterpay-express-button`). This allows you to have multiple buttons on the same page.
3. Set the entry point using the `data-Afterpay-entry-point` attribute. Allowed values are:
   * `product-page`
   * `mini-cart`
   * `cart`
4. Set the button label using the `data-Afterpay-checkout-button-label` attribute. This identifies the button for analytics or tracking purposes.

```html
<button id="Afterpay-express-button"
        data-Afterpay-entry-point="mini-cart"
        data-Afterpay-checkout-button-label="Check out using Cash App Afterpay">
  Check out using Cash App Afterpay
</button>
```

### Button options

Multiple button styles are available, each clearly communicating the next step to the customer.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Button Types - All in one.png" alt="Button Types - All in one.png" noZoom />

<Info>
  Integration assets are available 

  [here](/cash-app-afterpay/guides/welcome/migrate-from-afterpay-to-cash-app-afterpay/brand-assets)

  , or contact your Cash App Afterpay merchant services representative.
</Info>

## Create checkout

### Load Afterpay.js

Add the Afterpay.js script to your website. Set the `onload` attribute to point to a custom function that will initialize the popup (for example, `initAfterpay`).

```js
<script src="https://portal.sandbox.Afterpay.com/Afterpay.js? async onload="initAfterpay()">
  </script>
```

### Initialize the popup window

Define your `initAfterpay()` function before loading the script. This function uses `Afterpay.initializeForPopup()` to configure the express checkout behavior. Configure the following properties:

* `countryCode`: Your merchant account's two-character ISO 3166-1 code
* `target`: The ID or class of the button that triggers checkout
* Set the flag `shippingOptionRequired` to `false`
* Handle lifecycle events:
  * `onCommenceCheckout`: Retrieve the Afterpay token from your server, then call `actions.resolve(TOKEN)` to start checkout.
  * `onComplete`: See "[finalize the order](#finalize-the-order)" for details.

```html

<html>
  <head>
    <script>
      // ensure this function is defined before loading afterpay.js
      function initAfterpay () {
        AfterPay.initializeForPopup({
          countryCode: 'US',
          onCommenceCheckout: function (actions) {
            /* retrieve afterpay token from your server */
            /* then call `actions.resolve(token)` */
          },
          onComplete: function (data) {
            /* handle success/failure of checkout */
          },
          target: '#afterpay-button',
          shippingOptionRequired: false,
        })
      }
    </script>
    <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="initAfterpay()">
    </script>
  </head>
  <body>
    <button id="afterpay-button" 
    data-afterpay-entry-point="mini-cart">
      Checkout now with Cash App Afterpay
    </button>
  </body>
</html>
```

### Customer completes checkout

When the customer clicks the Cash App Afterpay checkout button, a popup opens or they're sent to your redirect link. The customer is prompted to log in and review their order details. They can select a payment method and delivery address.

After confirming their order, the popup closes and the customer returns to your site. Checkout completion is communicated via the `onComplete` callback.

## Finalize the order

When the customer completes Cash App Afterpay express checkout, the `onComplete` Javascript function is called. It receives an `event` argument with a `data` field containing the following properties:

| **Property**        | **Type**          | **Description**                                          |
| ------------------- | ----------------- | -------------------------------------------------------- |
| `status`            | string            | The order status: `"SUCCESS"` or `"CANCEL"`              |
| `orderToken`        | string            | The order token provided when initializing the checkout. |
| `merchantReference` | string (optional) | The merchant’s ID or reference number for the order.     |
| `orderInfo`         | object (optional) | The order info (if available) from the checkout.         |

**orderInfo data properties**

| **Property**      | **Type**   | **Description**                                                                             |
| ----------------- | ---------- | ------------------------------------------------------------------------------------------- |
| `shippingAddress` | `Contact`  | The shipping address for the order.                                                         |
| `consumer`        | `Consumer` | Contains the user’s `givenNames`, `surname`, and `email`. `phoneNumber` isn't defined here. |

```js
Afterpay.initializeForPopup({
  // ...
  onComplete: function (event) {
    if (event.data.status == "SUCCESS") {
      // The consumer has confirmed the payment schedule.
      // Call your server here to retrieve the order details.
    } else {
      // The consumer cancelled the payment or closed the popup window.
    }
  },
});
```

### Get order details

Retrieve the transaction details by calling the Get Checkout endpoint. This is the source of truth for the order. It includes the user’s name, email address, delivery address, phone number, and order total.

### Continue the checkout process

After getting the order details, continue the checkout on your site. To continue:

* Prefill your checkout using the Cash App Afterpay order details
* Have the customer select a delivery method
* Optionally, offer promo codes and allow changes to the order details
* Display the Cash App Afterpay [checkout widget](/cash-app-afterpay/guides/api-development/additional-features/checkout-widget) on the final review page or at all steps of your checkout. We recommend setting up the checkout widget before continuing.

<Warning>
  The Afterpay connected checkout widget is 

  **mandatory**

   for deferred shipping.
</Warning>

### Capture payment

You can capture payment using either the immediate payment flow or the deferred payment flow. For express checkout, the payload must include an `amount` field, which verifies that the final amount matches the amount including the shipping and taxes.

<Note>
  This section uses code examples from the immediate payment flow, but you can adapt these to use the deferred payment flow.
</Note>

For deferred shipping, in addition to the required `amount` field, include these additional fields in the payload. These are required to verify that the final order amount and payment schedule match the submitted order details.

* `isCheckoutAdjusted`: Indicates whether changes were made since order creation
* `items`: Updated list of order items (if changed)
* `shipping`: Updated shipping address (if changed)
* `paymentScheduleChecksum`: Latest value from your widget's `onChange` call (see Getting the widget's state)

```curl
curl --request POST \
  --url https://api-sandbox.Afterpay.com/v2/payments/capture \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"token":"YOUR_TOKEN", "amount":{"amount":"10.00", “currency”: “AUD”},  "isCheckoutAdjusted":true, "shipping":{"name":"Joe Consumer","line1":"123 Fake Street", "postcode":"3000", "region":"VIC", "countryCode":"AU"}, "items":[{"price":{"amount":"10.00", "currency":"AUD"}, "name":"item1", "quantity":1}], "paymentScheduleChecksum":"YOUR_PAYMENT_SCHEDULE_CHECKSUM" }'
```

If the final amount (including shipping and taxes) or the `paymentScheduleChecksum` doesn't match the expected values, the request will be rejected.

Once payment is captured, the express checkout order is complete.

#### Data payload properties

| Property                  | Type    | Description                                                                                                                                 |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`                   | String  | (required) The token returned in the Create Checkout request.                                                                               |
| `amount`                  | Money   | (required) Amount to be checked against the amount including shipping and taxes. If the amounts do not match, the request will be rejected. |
| `merchantReference`       | String  | Order id or reference this order corresponds to.                                                                                            |
| `isCheckoutAdjusted`      | Boolean | Whether there have been changes to the order since the initial order creation.                                                              |
| `paymentScheduleChecksum` | String  | A unique value representing the payment schedule that must be provided when there has been changes since the initial order creation.        |
| `items`                   | Item\[] | An array of order items that have been updated  to be provided if it has changed since the initial order creation.                          |
| `shipping`                | Contact | The shipping address for this order to be provided if it has changed since the initial order creation.                                      |

<Note>
  For Cross Border Trade orders, ensure that the currency is consistent throughout the entire checkout flow.

  For example, if you're a UK merchant displaying a 100 GBP order in AUD for an Australian consumer on your site. When initiating Afterpay checkout, If you initiate checkout by sending us the order amount in GBP (e.g. 100 GBP), then at capture the final order amount must also be in GBP.
</Note>

## Optional features

### Target multiple checkout buttons

If you have multiple checkout buttons on the same page, these can be targeted by adding a common class to each of these buttons:

```html
<button class="Afterpay-express-button”>
  Button 1 - Checkout using Afterpay Express
</button>
<button class="Afterpay-express-button”>
  Button 2 - Checkout using Afterpay Express
</button>
```

Then, set the target in the Afterpay.js initialize function with the common class. For example, set target in `initializeForPopup`:

```js
Afterpay.initializeForPopup({
  // ...
  target: ".Afterpay-express-button",
});
```

### Use a redirect flow

With deferred shipping, you can also use a redirect flow with express checkout. There are a few main differences when setting up the button for redirect, including:

* Creating an order token for redirect
* Using the `initializeForRedirect` method
* Redirecting the customer to finalize the order

To set up your redirect flow, first create an Afterpay order token using the Create Checkout API. Make sure to set the `mode` to `express`.

```curl
curl --request POST \
  --url https://api-sandbox.Afterpay.com/v2/checkouts \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"amount":{"amount":"10.00", “currency”: “AUD”}, “mode”: “express”, "merchant":{"redirectConfirmUrl":"https://example.com/checkout/confirm", "redirectCancelUrl":"https://example.com/checkout/cancel"}}'
```

Then, start by creating the Cash App Afterpay express checkout button, adding an entry point, and loading Afterpay.js. This is similar to the popup flow.

In your onload function, initialize the redirect flow by calling `initializeForRedirect` and configure the following:

* `countryCode`: The two-character ISO 3166-1 code for your merchant account
* `addressMode`: Use a mode without shipping options, as integrated shipping isn't supported for redirect flows.
* `target`: The ID or class of the button that initiates checkout
* Handle lifecycle events:
  * `onCommenceCheckout`: Retrieve the Afterpay token from your server, then call `actions.resolve(TOKEN)` to start the checkout process.

```html
<html>
  <head>
    <script>
      // ensure this function is defined before loading Afterpay.js
      function initAfterpay () {
        Afterpay.initializeForRedirect({
          countryCode: 'AU',
          onCommenceCheckout: function(actions) {
            /* retrieve Afterpay token from your server */
            /* then call `actions.resolve(token)` */
          },
          target: '#Afterpay-express-button',
          addressMode: Afterpay.ADDRESS_MODES.ADDRESS_WITHOUT_SHIPPING_OPTIONS,

        })
      }
    </script>
   <script src="https://portal.sandbox.Afterpay.com/Afterpay.js? async onload="initAfterpay()">
   </script>
  </head>
  <body>
    <button id="Afterpay-express-button" 
    data-Afterpay-entry-point="mini-cart">
      Checkout using Afterpay Express
    </button>
  </body>
</html>
```

#### Address mode

To support different shipping types in the checkout, configure the `addressMode` property using one of the provided constants in the format `Afterpay.ADDRESS_MODES.<NAME>`, where `<NAME>` is one of the following:

| Constant                                         | Description                                                                                                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ADDRESS_WITHOUT_SHIPPING_OPTIONS`               | Displays checkout with the option for the customer to configure their shipping address only.                                                                 |
| `SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS` | Displays checkout with the option for the customer to configure their shipping address only with the intention to continue their order back on the merchant. |
| `NO_ADDRESS`                                     | Displays checkout with the option for the customer to configure their shipping address only with the intention to buy now.                                   |

Next, finalize the order. When you created the Afterpay order token for redirect, you defined the properties `redirectConfirmUrl` and `redirectCancelUrl`. After the customer completes Afterpay express checkout, these properties are used to direct them to the specified URL:

* If successful, they are redirected to `redirectConfirmUrl`
* If cancelled, they are redirected to `redirectCancelUrl`

Once the customer returns to your site, follow the steps to get the order details.

## Errors

The following errors can occur during Cash App Afterpay express checkout with deferred shipping:

| **Error**                                                  | **How to Proceed**                                                                                                                                           |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Uncaught ReferenceError: Afterpay is not defined`         | Ensure that `Afterpay.js` is being loaded on your page before referencing it, e.g. by using the `onload` script attribute.                                   |
| `Uncaught ReferenceError: initAfterpay is not defined`     | Ensure that `initAfterpay` is defined **before** the script tag that loads `Afterpay.js`.                                                                    |
| Afterpay popup opens but doesn't launch a checkout         | Ensure your `onCommenceCheckout` handler has no errors (check the console), and that it calls `actions.resolve` with a valid token.                          |
| `onComplete` callback is not called when checkout finishes | This can occur due to issues with `postMessage` communication, especially with in-app browsers. Contact Cash App Afterpay with steps to replicate the issue. |

---

# Express checkout reference

## Sequence diagram

Express checkout has similar behaviour across both deferred and integrated shipping. The sequence diagram below shows a high-level checkout sequence for a customer using integrated shipping.

<div>
  ```mermaid
  ---
  config:
    sequence:
      mirrorActors: true
      width: 250
  ---
  %%{
    init: {
      'theme': 'base',
      'themeVariables': {
        'primaryColor': '#FFF',
        'primaryTextColor': '#000',
        'primaryBorderColor': '#000',
        'lineColor': '#000',
        'secondaryColor': '#fff',
        'tertiaryColor': '#fff',
        'noteBkgColor': '#fff',
        'noteBorderColor': '#000'
      }
    }
  }%%
  sequenceDiagram
      title Cash App Afterpay Express Checkout Happy Path
      participant C as Consumer
      participant M as Merchant
      participant AP as $Afterpay
      participant XCO as Express Checkout
      Note over C,XCO: shopping cart
      C->>M: Checkout using $Afterpay express
      M->>AP: Create order
      AP-->>M: Order token
      Note over C,XCO: $Afterpay checkout
      M-->>C: Open $Afterpay Checkout
      C->>XCO: Select shipping address
      XCO->>M: Shipping address change callback
      M-->>XCO: Shipping options and taxes
      C->>XCO: Choose shipping method
      XCO->>XCO: Update order value
      C->>XCO: Complete order
      XCO->>M: onComplete
      Note over C,XCO: Review and confirm
      M->>AP: Get order
      AP-->>M: Afterpay order
      M->>M: Verify transaction
      M->>C: Review order
      C->>M: Confirm
      M->>AP: Capture payment
  ```
</div>

1. A customer (consumer) chooses *Checkout with Cash App Afterpay Express* from the shopping cart or product.
2. The merchant calls the *Create Order* or *Create Checkout* endpoint, passing an option to enable dynamic pricing in the Express Checkout.
3. The merchant uses the token in combination with the Javascript `afterpay.js` to direct the customer through the Cash App Afterpay Express checkout flow using the popup method.
4. The customer enters Express Checkout and selects the shipping address they want from their existing Cash App Afterpay details.
5. Cash App Afterpay calls the `onShippingAddressChange()` callback function on the merchant site to retrieve all shipping options and taxes for the chosen address.
6. The customer selects the shipping method and the order total, including the payment schedule, is updated to include the relevant shipping and taxes.
7. The customer confirms their Cash App Afterpay order and Cash App Afterpay notifies the merchant using the `onComplete()` callback function.
8. The merchant verifies the transaction by fetching the Order from Cash App Afterpay and comparing it to their own records.
9. The merchant shows the customer a confirmation page (optional).
10. The customer confirms their order. The merchant calls Cash App Afterpay to capture the payment, passing the calculated order amount for verification.

```json
AfterPay.initializeForPopup({
  countryCode: 'US',
  onCommenceCheckout: function(actions) {
    /* retrieve cash app afterpay token from your server */
    /* then call `actions.resolve(token)` */
  },
  onShippingAddressChange: function (data, actions) {
    /* required for Integrated Shipping  */
    /* address in `data` */
    /* calc options, then call `actions.resolve(options)` */
  },
  onShippingOptionChange: function (data) {
    /* optional - chosen option in `data` */
  },
  onComplete: function (data) {
    /* handle success/failure of checkout */
  },
  target: '#afterpay-express-button',
  buyNow: false,
  pickup: false,
  shippingOptionRequired: true
})
```

<Note>
  Integrated Shipping is enabled by default for Express orders. To disable it, set `shippingOptionRequired` to false.
</Note>

**Integrated and Deferred Shipping**

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay-EC-Flows-2.png" alt="Afterpay-EC-Flows.png" noZoom />

**Flow Diagram Key**

* Auth = Payment authorization
* Cart = Online shopping cart or basket
* Checkout = Checkout page
* Config = Configuration
* EC = Express Checkout
* PDP = Product Display Page

### Feature variant combinations

**InitializeForPopup only**

addressMode: `ADDRESS_WITH_SHIPPING_OPTIONS` - no widget needed.

This is the default configuration.

Within the Cash App Afterpay Checkout flow, the customer can:

* Select a shipping address from within their Cash App Afterpay account.
* View shipping options from the merchant and select one.
* Complete the order

The merchant must:

* Listen to the `onShippingAddressChange` and provide the relevant shipping options.

**Recommended:** for orders that need to be shipped to the customer’s address and have up to five simple shipping options

***

addressMode: `PICKUP_FROM_ORDER_ADDRESS` - no widget needed.

Within the Cash App Afterpay Checkout flow, the customer can:

* See their pickup address (previously selected on the merchant site), but not change it
* View pickup options from the merchant and select one
* Complete the order

The merchant must:

* Send pickup address when creating an order token

* Listen to the `onShippingAddressChange` and provide the relevant pickup options

**Recommended** for orders picked up at a specific location (e.g. your physical store)

***

addressMode: `SHIP_TO_ORDER_ADDRESS` - no widget needed.

Within the Cash App Afterpay Checkout flow, the customer can:

* See their chosen order address from the merchant site (but not change it)

* View shipping options from the merchant and select one\
  Complete the order

The merchant must:

* Send shipping address when creating an order token

* Listen to the `onShippingAddressChange` and provide the relevant shipping options

**Recommended** for orders to be shipped to the customer’s address chosen on your site (before launching Express Checkout). In this case, the address displayed within the Cash App Afterpay checkout flow is locked and customers cannot change it.

***

**initializeForPopup or initializeForRedirect**

addressMode: `NO_ADDRESS` - no widget needed.

Within the Cash App Afterpay Checkout flow, the customer can:

* Complete the order

Customers cannot do the following actions within the Cash App Afterpay checkout flow

* View a shipping or pickup address
* View shipping options from the merchant and select one

**Recommended** for when there is no shipping or pickup needed (eg.digital goods or services).

***

addressMode: `SHIP_TO_ORDER_ADDRESS_WITHOUT_SHIPPING_OPTIONS` - no widget needed.

Within the Cash App Afterpay Checkout flow, the customer can:

* See their chosen order address from the merchant site (but not change it)
* Complete the order

Customer cannot do the following actions within the Cash App Afterpay checkout flow:

* View shipping options from the merchant and select a shipping option

The merchant must:

* Send the shipping address when creating an order token

**Recommended** for orders that must be shipped to the customer’s address chosen on your site (before launching Express Checkout), and there are no shipping options available for customers to choose from.

## Security - postMessage()

`afterpay.js` uses the HTML `postMessage()` API to exchange information between the Cash App Afterpay checkout popup and the page that spawned it. This allows Javascript code running on different origins to communicate with each other in a bidirectional manner.

The bidirectional communication allows a merchant to dynamically update shipping options and transaction information based on a chosen shipping address.

`afterpay.js` hides this complexity and restricts the use of `postMessage()` to ensure a secure environment. Specifically:

* Cash App Afterpay’s checkout window only receives messages from the merchant window, and vice versa

* Correctly handles multiple concurrent, and possibly out-of-order requests

* Message data is validated and sanitized

Using `postMessage()` in this way is considered very secure. For more information please refer to the [specification](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).

---

# Cash App Afterpay On File

Cash App Afterpay On File allows customers to save Cash App Afterpay as a payment method on your website. Similar to storing a credit card on file, this simplifies future transactions and supports recurring payments like subscriptions.

Benefits include:

* **Payment flexibility:** You can offer both one-time and recurring purchases to your customers using Cash App Afterpay.
* **Faster checkout:** Once a customer links their Cash App Afterpay account, they’re not required to input their Cash App Afterpay account details for future Cash App Afterpay purchases. This reduces friction – which is especially important for mobile transactions and frequent purchases.
* **Improved conversion and retention:** A simpler repeat purchase experience encourages customers to return, boosts conversion rates, and increases customer lifetime value.

Supported use cases:

* **Customer-initiated transaction (CIT):** A payment initiated by the customer using their saved Cash App Afterpay account details, while the customer is present on your website.
  * Example: any one-off customer-initiated purchase on your website
* **Merchant-initiated transaction (MIT):** A payment initiated by the merchant, while the customer is not present on your website. These payments can be fixed or variable amounts.
  * Example: regular and ongoing subscriptions and memberships.

When a customer saves Cash App Afterpay as a payment method, a grant is created. A grant is a payment token associated with a specific customer that merchants can use to initiate future payments. After any on file payments are processed, the customer receives a Cash App Afterpay order confirmation email, regardless of whether the payment is customer-initiated or merchant-initiated.

<Info title="Important">
  On file payment functionality is available only in Australia, New Zealand, and the United States. It's supported only on API v2.

  You must be assessed and approved by Cash App Afterpay before you can make Cash App Afterpay On FFile available to your customers. Reach out to your Cash App Afterpay account manager for more information.
</Info>

## Set up Cash App Afterpay On File

There are two ways to implement Cash App Afterpay On File: customers can save their Cash App Afterpay details in a virtual wallet outside the checkout flow, or they can save their Cash App Afterpay details during the checkout process itself.

### Add Cash App Afterpay to a virtual wallet

Create a Cash App Afterpay grant outside of a checkout flow, in a virtual wallet for your store.

#### Step 1: Start the approval process

Call the Create Grant Approval endpoint [(/v2/grants/approvals)](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/start-grant-approval). This provides Cash App Afterpay with customer information, grant information, and the URL to direct the customer to when they complete the Cash App Afterpay approval flow.

**Request**

```json
{
    "consumer": {
        "phoneNumber": "3526669673",
        "givenNames": "John",
        "surname": "Doe",
        "email": "{{email}}"
    },
    "merchant": {
        "redirectConfirmUrl": "https://www.afterpay-merchant.com/confirm",
        "redirectCancelUrl": "https://www.afterpay-merchant.com/cancel"
    },
    "grants": [
        {
            "type": "ON_FILE",
            "merchantReference": "merchant-internal-ref"
        }
    ]
}
```

**Response**

```json
{
    "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h",
    "expires": "2025-07-23T18:39:58.634Z",
    "redirectCheckoutUrl": "https://portal.afterpay.com/us/checkout/?token=001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h"
}
```

#### Step 2: Redirect to checkout

Redirect the customer to checkout using the `redirectCheckoutUrl` returned from the Create Grant Approval call. See [Create a Checkout](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout) for instructions on launching a checkout.

#### Step 3: Create on file grant

If the checkout is successful, Cash App Afterpay redirects the customer to the URL you specified in the Create Grant Approval call. Next, create the grant by calling the Create Grant endpoint [(/v2/grants)](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/create-grant). This call creates a grant and returns a grant ID. Save this ID for your customer’s future transactions.

**Request**

```json
{  
         "requestId": "{{$randomUUID}}",
         "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h"
}
```

**Response**

```json
{
    "grant": {
        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
        "created": "2025-07-23T16:46:55.476Z",
        "type": "ON_FILE",
        "status": "ACTIVE",
        "merchantReference": "merchant-internal-ref"
        "email": "tes***@s***.com",
        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
    }
}
```

<Note>
  Grants can be revoked by the customer or merchant at any time. We recommend subscribing to the [AgreementStatusUpdated](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/grant-status-updated) webhook.
</Note>

### Save Cash App Afterpay details during checkout

Create a Cash App Afterpay grant during the checkout flow. For example, a customer can purchase a monthly subscription and pay for the first installment.

<Note>
  Create the grant **before** finalizing the purchase. If the purchase is finalized first, the grant can't be created.
</Note>

#### Step 1: Create a checkout

Create a checkout using the Create Checkout endpoint [(/v2/checkouts)](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) using the Grants object with type `ON_FILE`. See [here](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout) for instructions on launching a checkout.

**Request**

```json
{
    "amount": {
        "amount": "15.00",
       "currency" : "{{currency}}"
    },
    "consumer": {
        "phoneNumber": "61450675141",
        "givenNames": "",
        "surname": "",
        "email": "{{email}}"
    },
    "merchant": {
        "redirectConfirmUrl": "https://www.afterpay-merchant.com/confirm",
        "redirectCancelUrl": "https://www.afterpay-merchant.com/cancel"
    },
    "merchantReference": "merchantOrder-1234",
    "grants": [
        {
        "type": "ON_FILE",
        "merchantReference": "merchant-grant-internal-ref"
        }
    ]
}
```

**Response**

```json
{
    "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h",
    "expires": "2025-07-23T18:39:58.634Z",
    "redirectCheckoutUrl": "https://portal.afterpay.com/us/checkout/?token=001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h"
}
```

#### Step 2: Create and store the on file grant

If the checkout is successful, Cash App Afterpay redirects the customer to the URL you specified in the Create Checkout call. Next, create the grant by calling the Create Grant endpoint [(/v2/grants)](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/create-grant). This endpoint creates a grant and returns a grant ID. Save this ID for your customer’s future transactions.

**Request**

```json
{  
         "requestId": "{{$randomUUID}}",
         "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h"
}
```

**Response**

```json
{
    "grant": {
        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
        "created": "2025-07-23T16:46:55.476Z",
        "type": "ON_FILE",
        "status": "ACTIVE",
        "merchantReference": "merchant-grant-internal-ref"
        "email": "tes***@s***.com",
        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
    }
}
```

#### Step 3: Capture payment

Now that you have a successful checkout pre-approval and an on file grant, choose when you want to capture the payment. You can either capture immediately or authorize and capture at a later time (authorizations last for 13 days before automatically expiring).

* **Immediate capture:** Call the Capture Full Payment endpoint [(/v2/payments/capture)](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment), following the instructions [here](/cash-app-afterpay/guides/api-development/api-quickstart/immediate-capture).
* **Deferred capture:** Call the Auth endpoint [(/v2/payments/auth)](/cash-app-afterpay/api-reference/reference/payments/auth), following the instructions [here](/cash-app-afterpay/guides/api-development/api-quickstart/deferred-capture).

**Request**

```json
{
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h",
  "merchantReference": "merchant-order-123"
}
```

**Response**

```json
{
  "id": "300000016189",
  "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h",
  "status": "APPROVED",
  "created": "2024-03-11T20:11:42.487Z",
  "originalAmount": {
    "amount": "37.00",
    "currency": "USD"
  },
  "openToCaptureAmount": {
    "amount": "0.00",
    "currency": "USD"
  },
  "paymentState": "AUTH_APPROVED",
  "merchantReference": "updated-k6-reference-utaddnpx",
  "refunds": [],
  "orderDetails": {
    "consumer": {},
    "billing": {
      "name": "Joe Customer",
      "line1": "1004 New Avenue",
      "postcode": "94121",
      "countrycode": "US",
      "phoneNumber": "2120000000"
    },
    "shipping": {
      "name": "Joe Customer",
      "line1": "1004 New Avenue",
      "postcode": "94121",
      "countrycode": "US",
      "phoneNumber": "2120000000"
    },
    "courier": {
      "shippedAt": "2024-01-01T08:00:00Z",
      "name": "FedEx",
      "tracking": "000 000 000 000",
      "priority": "STANDARD"
    },
    "items": {
      "name": "Blue Carabiner",
      "sku": "12341234",
      "quantity": 1,
      "price": {
        "amount": "40.00",
        "currency": "USD"
      }
    },
    "categories": {
      "name": "Jeans",
      "sku": "123412345",
      "quantity": 1,
      "price": {
        "amount": "20.00",
        "currency": "USD"
      },
      "categories": null
    }
  },
  "discounts": [],
  "shippingAmount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "taxAmount": {
    "amount": "0.00",
    "currency": "USD"
  },
  "events": {
    "id": "2dYbLXpOtEPQbg1DT7x9D8R4oCY",
    "created": "2024-03-11T20:11:43.897Z",
    "expires": null,
    "type": "CAPTURED",
    "amount": {
      "amount": "37.00",
      "currency": "USD"
    },
    "paymentEventMerchantReference": "k6-gsrdqspusf"
  }
}
```

## Create an on file payment

Once a grant is created, you can use the grant ID to place additional Cash App Afterpay orders.

To create an order with the grant, call the Orders API [(/v2/orders)](/cash-app-afterpay/api-reference/reference/orders/create-grant) and include the stored grant ID in the request.

Cash App Afterpay checks the customer’s eligibility at order creation, so we recommend making this call at the beginning of your checkout process if Cash App Afterpay is the selected payment method. If the order amount changes before the on file payment is created, create a new order with the updated amount; the original order is automatically deleted by Cash App Afterpay.

Once you've successfully created an order, use the token from the response to call either the Auth endpoint [(/v2/payments/auth)](/cash-app-afterpay/api-reference/reference/payments/auth) or the Capture Full Payment endpoint [(/v2/payments/capture)](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment).

<Note>
  On file payments require extra metadata, such as payment initiation actor and subscription details, to ensure compliant usage and improve underwriting decisions. Required fields may include:

  * enrichments.initiation.actor (required)
  * enrichments.subscription.type (required if subscription)
  * enrichments.subscription.interval (required if subscription)
  * enrichments.subscription.intervalCount (required if subscription)
</Note>

**Request**

```json
{  
         "requestId": "{{$randomUUID}}",
         "grantId": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
         "amount": {
            "amount": "125.00",
            "currency": "USD"
        },
        "enrichments": {
            "initiation": {
                "actor": "CUSTOMER"
            }
        }
}
```

**Response**

```json
{
    "token": "001.1hrgccv8a6th0pklh7mqranu58tb1lllau9fhngl77i44rtk",
    "expires": "2025-07-23T19:28:06.880Z"
}
```

## Manage existing grants

Once a grant has been created, you can use it to initiate new on file payments or retrieve the grant details using the Retrieve Grant endpoint [(/v2/grants/\{grantId})](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/get-grant).

If a customer decides to remove Cash App Afterpay as a saved payment method on your website, use the Revoke Grant endpoint [(/v2/grants/\{grantId}/revoke)](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/revoke-grant) so that the grant ID can be deactivated by Cash App Afterpay.

**Response**

```json
{
    "grant": {
        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
        "created": "2025-07-23T16:46:55.476Z",
        "type": "ON_FILE",
        "status": "CANCELLED",
        "merchantReference": "merchant-internal-ref"
        "cancelled": "2025-07-23T18:15:09.316Z",
        "email": "tes***@s***.com",
        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
    }
}
```

Customers can also revoke a grant within the Cash App Afterpay app. Merchants should subscribe to the [GrantStatusUpdated](/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/schemas/grant-status-updated) webhook.

```json
{
  "type": "on_file_grant.status.updated",
  "eventId": "87f5ded7-2747-4e31-95ee-8993e0ae8663",
  "createdAt": "2025-08-22T19:34:37.497Z",
  "data": {
    "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
    "type": "ON_FILE_GRANT",
    "object": {
      "grant": {
        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
        "created": "2025-07-23T16:46:55.476Z",
        "type": "ON_FILE",
        "status": "CANCELLED",
        "cancelled": "2025-08-22T19:34:35.012Z"
      }
    }
  }
}
```

<Note>
  Merchants can use the `consumerReference` field associated with a grant ID to map to their own customer identifier. The email field, which is masked, can be used as a customer-facing identifier.
</Note>

## Considerations

1. Customers should be able to revoke grants (unlink Cash App Afterpay as a saved payment method) on your website. Customers should also be notified of any price change to a subscription at least 30 days in advance, or in adherence to any applicable laws and legal requirements.
2. Merchants are strongly encouraged to implement Cash App Afterpay's [checkout widget](/cash-app-afterpay/guides/api-development/additional-features/checkout-widget#with-on-file-grant) for grants, as it allows merchants to show the required disclosures and payment schedule details on their checkout page prior to customers finalizing their purchases.

---

# Display the checkout widget

Use the checkout widget to display the Cash App Afterpay payment schedule on your website. There are three ways to use the widget:

* **[Connected](#connected-widget):** Displayed after the checkout process, using an order token. If the order amount changes post-checkout, use the connected widget to update the payment schedule

* **[Unconnected](#unconnected-widget):** Displayed before the customer starts the checkout process, with no order token—just an amount

* **[With on file grant](#with-on-file-grant):** Displayed before the customer places the order, using an alias from a grant

The widget is responsive and can fit into any container with a minimum width of 300px. You can render the widget into a target container on your page using JavaScript.

## Connected widget

Use the connected widget on your checkout page **after** a customer completes the Cash App Afterpay checkout flow. This widget serves several purposes:

* Ensures that the customer sees and agrees to an accurate payment schedule.
* Verifies that the final amount charged matches what the customer was shown during checkout.
* Provides the merchant with important information, like the first payment amount.
* Informs the merchant if there are any barriers to purchase, such as exceeding the Cash App Afterpay payment limit.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Connected Widget.png" alt="Connected Widget.png" noZoom />

<Info title="Important">Only show the connected widget after the customer has successfully completed the Cash App Afterpay checkout (when the onComplete status is SUCCESS). You must display the connected widget during the Deferred Shipping flow.</Info>
The connected widget requires:

* The Cash App Afterpay checkout token to retrieve and render the payment schedule.
* The final order amount

```json
<html>
 <body>
   <div id="afterpay-widget-container"></div>
   <script>
     // Ensure this function is defined before loading afterpay.js
     function createAfterpayWidget () {
       window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
         token: 'YOUR_TOKEN', // required
         amount: { amount: "123.45", currency: "USD" }, // required, amount of the total order post checkout, must be a positive value
         target: '#afterpay-widget-container',
         locale: 'en-US', 
         onReady: function (event) {
           // Fires when the widget is ready to accept updates.
           // An initial call to "update" must be made here.
         },
         onChange: function (event) {
           // Fires after each update and on any other state changes.
           // See "Getting the widget's state" for more details.
         },
         onError: function (event) {
           // See "Handling widget errors" for more details.
         },
       })
     }
   </script>
   <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
   </script>
 </body>
</html>
```

### Capturing payment with the connected widget

Because you can update the order after checkout has completed, the connected widget has
unique considerations. When calling the /v2/payments/capture API, the payload must contain the required amount field plus additional properties. This allows Cash App Afterpay to verify that the final order amount and payment schedule match the calculated values from the corresponding order details. These properties are:

* `isCheckoutAdjusted`: Indicates whether any changes have been made to the order since the initial creation
* `items`: The list of order items if it has changed
* `shipping`: The shipping address if it has changed
* `paymentScheduleChecksum`: The latest paymentScheduleChecksum retrieved from your widget’s `onChange` call (see ‘Getting the widget’s state’).

```json
curl --request POST  
  --url <https://api-sandbox.afterpay.com/v2/payments/capture>  
  --header 'accept: application/json'  
  --header 'content-type: application/json'  
  --data '{"token":"YOUR_TOKEN", "amount":{"amount":"10.00", “currency”: USD},  "isCheckoutAdjusted":true, "shipping":{"name":"Joe Customer","line1":"123 Fake Street", "postcode":"12345", "region":"NY", "countryCode":"US"}, "items":[{"price":{"amount":"10.00", "currency":"USD"}, "name":"item1", "quantity":1}], "paymentScheduleChecksum":"YOUR_PAYMENT_SCHEDULE_CHECKSUM" }'
```

<Info title="Important">
  If the final 

  `amount`

   doesn’t match the calculated 

  `amount`

   (including shipping, taxes, etc.), or if the 

  `paymentScheduleChecksum`

   doesn’t match the calculated payment schedule, the capture request will be rejected.
</Info>

| Property                  | Type              | Description                                                                                                                          |
| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `token`                   | String (required) | The token returned in the Create Checkout request.                                                                                   |
| `amount`                  | Money (required)  | Amount to be checked against the amount including shipping and taxes. If the amounts do not match, the request is rejected.          |
| `merchantReference`       | String            | Order ID or reference this order corresponds to.                                                                                     |
| `isCheckoutAdjusted`      | Boolean           | Whether there have been changes to the order since the initial order creation.                                                       |
| `paymentScheduleChecksum` | String            | A unique value representing the payment schedule that must be provided when there has been changes since the initial order creation. |
| `items`                   | Item              | An array of order items that have been updated  to be provided if it has changed since the initial order creation.                   |
| `shipping`                | Contact           | The shipping address for this order to be provided if it has changed since the initial order creation.                               |

### Getting the widget's state

After each update and on any other state changes, the onChange callback is called with an HTML event argument. At this point the widget’s state is retrieved from event.data, which will have the properties in the table:

| Property                  | Type    | Description                                                                                                                                                                                                                           |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isValid`                 | Boolean | Whether the order is okay to proceed. If false, the order should be prevented from completing.                                                                                                                                        |
| `amountDueToday`          | Money   | The amount owing today. Displaying this value in your Order Summary will give your customer more confidence when they place their order. `amountDueToday.format()` returns a formatted string that you can easily display in your UI. |
| `paymentScheduleChecksum` | String  | A unique value representing the payment schedule that must be provided when capturing the order.                                                                                                                                      |
| `error`                   | Error   | The current error state, if any.                                                                                                                                                                                                      |

We recommend using the `isValid` and `amountDueToday` states to update your checkout UI as described above, and persisting the `paymentScheduleChecksum` on your backend to be used when capturing. The widget itself informs customers what has gone wrong when `isValid` is false.

In addition to the `onChange` callback, these states are exposed as properties on the widget and can be accessed directly at any time, for example:

```
var isValid = afterpayWidget.isValid
var amountDueToday = afterpayWidget.amountDueToday
var paymentScheduleChecksum = afterpayWidget.paymentScheduleChecksum
var error = afterpayWidget.error
```

### Handling widget errors

| Property | Type                                                                    | Description                                   |
| -------- | ----------------------------------------------------------------------- | --------------------------------------------- |
| error    | [Error](/cash-app-afterpay/api-reference/reference/introduction/errors) | Representing the current error state, if any. |

Any errors on the widget trigger the `onError` callback with an HTML event (see table below), and have a false `isValid` status.

If the `onChange` callback is activated and fails due to an error, the `onError` event is also triggered for convenience. In this case, a response to `onError` events is not needed, provided all `onChange` events are handled.

#### `onError` event.data properties table

| Property  | Type                                                                    | Description                                                                                                                |
| --------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `isValid` | Boolean                                                                 | Whether the order is okay to proceed. For the `onError` event this will be **false** so prevent the order from completing. |
| `type`    | String                                                                  | For an `onError` event, the type is set to the value of **error**.                                                         |
| `error`   | [Error](/cash-app-afterpay/api-reference/reference/introduction/errors) | Represents the current error state.                                                                                        |

<Note>
  If you are getting errors during the rendering of the widget, open the browser console. The console may display some additional error loggings to help identify some common integration misconfigurations.
</Note>

## Unconnected widget

Use the unconnected widget on your checkout page **before** the customer starts the Cash App Afterpay checkout flow. This version of the widget displays an estimated payment schedule based on the initial order amount; this is only an approximation based on the initial order total.

The unconnected widget requires a defined positive `amount` to calculate the estimated payment schedule.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Unconnected Widget.png" alt="Unconnected Widget.png" noZoom />

If the order total changes (due to shipping method, promo code, or cart contents), the widget must be notified of the new amount. Only call the update function after the widget’s `onReady` callback has been triggered.

```json
<html>
 <body>
   <div id="afterpay-widget-container"></div>
   <script>
     // Ensure this function is defined before loading afterpay.js
     function createAfterpayWidget () {
       window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
         amount: { amount: "123.45", currency: "USD" }, // required, must be a positive value

         target: '#afterpay-widget-container',
         locale: 'en-US', 
         onReady: function (event) {
           // Fires when the widget is ready to accept updates.
           // An initial call to "update" must be made here.
         },
         onChange: function (event) {
           // Fires after each update and on any other state changes.
           // See "Getting the widget's state" for more details.
         },
         onError: function (event) {
           // See "Handling widget errors" for more details.
         },
       })
     }
   </script>
   <script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
   </script>
 </body>
</html>
```

## With on file grant

You can use the widget when customers place an order with an existing Cash App Afterpay On File grant. This is helpful for customers, allowing them to see their payment schedule despite not going through the Cash App Afterpay checkout flow.

To display the widget:

1. First, call the Create Grant Alias endpoint [(/v2/grants/alias)](/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/alias-grant) to retrieve the payment schedule token.
2. Pass the token to the widget.
3. If there are changes to the order total, call the `updateAmount` function to update the widget.

<Info title="Considerations for cross-border trade">
  Always ensure that the currency is consistent throughout the entire checkout flow. For Cross Border Trade orders, the checkout widget displays the payment schedule and 'Due today' amounts in the customer’s currency, which may be different from the currency on your site. The capture amount must be in the same currency in which the checkout is initiated.

  For example, you are an American merchant displaying a 100 USD order in AUD for an Australian customer on your site. When you start the Cash App Afterpay checkout, if you start the checkout by sending us the order amount in USD (e.g. 100 USD), then at capture the final order amount must also be in USD.

  Likewise, if you initiate checkout by sending us the order amount in AUD post currency conversion on your side (e.g. 150 AUD), ensure that the capture amount is sent in AUD.
</Info>

## Styling the checkout widget

### Standard widget

The default version of the widget displays accurate payment schedule information, the payment amount due today, and the legal disclaimer.

Here's an example of how to initialize the standard widget, and a sample function for updating the amount to a new value.

```html
<html>
  <body>
    <div id="afterpay-widget-container"></div>
    <script>
      // Ensure this function is defined before loading afterpay.js
      function createAfterpayWidget () {
        window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
          target: '#afterpay-widget-container',
          locale: 'en-US',
          amount: {
            amount: "1338.00",
            currency: "USD"
          },
          // Use your payment schedule token to reflect an accurate payment schedule to your customers
          paymentScheduleToken: "PAYMENT_SCHEDULE_TOKEN_PLACEHOLDER",
        })
      }

      function updateAmount() {
        window.afterpayWidget.update(
            amount: { amount: "1000.00", currency: "USD" }
        )
      }


    </script>
    <script src="https://portal.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
    </script>

    <button onclick="updateAmount()">Update amount</script>
  </body>
</html>
```

### Compact widget

This is a more compact version of the widget. It presents the same information as the standard widget, but takes up less space.

Here's an example:

```html
<html>
  <body>
    <div id="afterpay-widget-container"></div>
    <script>
      // Ensure this function is defined before loading afterpay.js
      function createAfterpayWidget () {
        window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
          target: '#afterpay-widget-container',
          locale: 'en-US',
          amount: {
            amount: "1338.00",
            currency: "USD"
          },
          style: {
             theme: "TIMELINE"
          },
          // Use your payment schedule token to reflect an accurate payment schedule to your customers
          paymentScheduleToken: "PAYMENT_SCHEDULE_TOKEN_PLACEHOLDER",
        })
      }
    </script>
    <script src="https://portal.afterpay.com/afterpay.js" async onload="createAfterpayWidget()">
    </script>
  </body>
</html>
```

### Style attributes

There is an optional style attribute that you can use to toggle particular features on or off in the widget. The current styles are:

* `border` - If false, the border around the widget container is removed. Default: true
* `heading` - If false, the heading “Your 4 interest-free payments” is removed.  Default: true
* `logo` - If false, the Cash App Afterpay logo is removed. Default: true
* `theme` (string) - allows you to customize the look of the widget. Following themes are available ‘CLASSIC’ | ‘TIMELINE’ | ‘COLLAPSIBLE’ | ‘MODAL’. Default: ‘CLASSIC’

Here are some theme examples:

**Timeline**
![Timeline.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Timeline.png)

**Collapsible**
![collapsible.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/collapsible-3.png)

**Collapsible (extended)**
![collapsible-expanded.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/collapsible-expanded.png)

**Modal**
![Modal.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Modal.png)

**Modal (open)**
!\[Modal open.png]\(../../assets/images/Modal open.png)

**Code example:**

```
window.afterpayWidget = new AfterPay.Widgets.PaymentSchedule({
  // ...
    style: {
        border: true, 
        heading: true, 
        logo: true,
        theme: ‘TIMELINE’, // ‘COLLAPSIBLE’‘MODAL’
   }
  // ...
});
```

---

# Adding Cash App Pay to Your Site

Cash App Pay is a fast and simple *pay now* payment method for your customers. Currently it is only available in the USA.

There are two ways customers can pay you with Cash App Pay:

* [Shopping from a Desktop Device with a QR code](#shopping-from-a-mobile-device-with-a-qr-code)

* [Shopping from a Mobile Device by Tapping](#shopping-from-a-mobile-device-by-tapping)

These two payment flows are summarized below:

#### Shopping from a Desktop Device with a QR Code

1. From their desktop device, the customer selects Cash App Pay as the payment method during checkout.

2. The customer holds their mobile device camera or Cash App’s QR scanner over the QR code that appears on the desktop screen to scan the QR code.

3. The customer follows the prompts on their mobile device to complete the transaction.

#### Shopping from a Mobile Device by Tapping

1. From their mobile device, the customer taps Cash App Pay to select it as the payment method during checkout.

2. The customer is redirected to Cash App, where they can follow the prompts to complete the transaction.

<Note>
  Remember that Cash App Pay is a **pay now** payment method. Customers use Cash App Pay to  pay for goods and services in a single payment at the time of purchase.

  Cash App Afterpay is a **pay later** payment method. Customers use Cash App Afterpay to pay for goods and services in several interest-free payments.
</Note>

## Appearance

If you implement Cash App Pay with Cash App Afterpay, expect the appearance of your checkout and payment pages to change slightly.

On checkout or other payment screens, Cash App Pay appears as a separate payment option alongside Cash App Afterpay. Cash App Pay is not within Cash App Afterpay, but provided alongside it. Customers with Cash App accounts can use their Cash App balance as a payment source to pay in installments.

## Availability

It is important you are aware of Cash App Pay availability along with its related products:

* Cash App Pay is only available in the USA

* Cash App Pay on file is only available in the USA

## Detailed Information

The following sections are on this page:

* [Integrating Cash App payments using the existing Cash App Afterpay API](#integrating-cash-app-payments-using-the-existing-cash-app-afterpay-api)
* [Mobile Redirection](#mobile-redirection)
* [Restarting Cash App Pay for a New Checkout Request](#restarting-cash-app-pay-for-a-new-checkout-request)
* [Payment refunds with Cash App](#payment-refunds-with-cash-app)
* [Settlement with Cash App](#settlement-with-cash-app)
* [Add Your Logo to the QR Code Scanner](#add-your-logo-to-the-qr-code-scanner)
* [Advanced Rendering Control](#advanced-rendering-control)

Cash App Pay on file has a page of its own:

* [Cash App Pay on file](/cash-app-afterpay/guides/api-development/add-cash-app-pay-to-your-site/cash-app-pay-on-file)

## Integrating Cash App Payments Using the Existing Cash App Afterpay API

<Warning title="Disclaimer">
  To successfully launch the Cash App Pay screenflow on your website's front-end, you must use the exact same JS script employed for [launching the Cash App Afterpay screenflow](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout).

  For example, `<script onload="initAfterPay()" src="https://portal.sandbox.afterpay.com/afterpay.js" async defer></script>`
</Warning>

Accepting Cash App Pay payments uses the standard API for the Cash App Afterpay [checkout process](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout), with your existing Cash App Afterpay credentials. The Cash App Afterpay backend handles the transaction with Cash App Pay. The implementation process is as follows:

1. Call the [Create Checkout API](/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1) with the addition of the following parameter `isCashAppPay: true` to create an order token.

2. Use the token in combination with the [Standard Checkout](/cash-app-afterpay/guides/api-development/api-quickstart/create-a-checkout) flow, but call `AfterPay.initializeForCashAppPay` instead of Afterpay. like in the code sample below:

   ```js
   function initAfterPay() {

       var cashAppPayOptions = {
           button: {
               size: 'small', // "medium" | "small"
               width: 'full', // "full" | "static"
               theme: 'dark', // "dark" | "light"
               shape: 'round' // "round" | "semiround"
           },
           onComplete: function(event) {
               const {
                   status,
                   cashtag
               } = event.data;
           },
           /* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */
           eventListeners: {
               "CUSTOMER_INTERACTION": ({
                   isMobile
               }) => {
                   console.log(`CUSTOMER_INTERACTION`)
                   if (isMobile) {
                       // captureMobileMetrics()
                   } else {
                       // captureDesktopMetrics()
                   };
               },
               "CUSTOMER_REQUEST_DECLINED": () => {
                   console.log(`CUSTOMER_REQUEST_DECLINED`)
               },
               "CUSTOMER_REQUEST_APPROVED": () => {
                   console.log(`CUSTOMER_REQUEST_APPROVED`)
               },
               "CUSTOMER_REQUEST_FAILED": () => {
                   console.log(`CUSTOMER_REQUEST_FAILED`)
               }
           }
       }
       AfterPay.initializeForCashAppPay({
           countryCode: "US",
           token: "ORDER_TOKEN_PLACEHOLDER",
           cashAppPayOptions
       });
   }
   ```

3. Add a div with `id="cash-app-pay"` where you want the Cash App Pay button to be rendered.

4. On clicking the button the customer is shown a QR code (on desktop).

   ![Cash App Pay QR Code](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/qrcode-cash-app-pay.png)

5. If the customer confirms the order, an Order Token, the customer's Cashtag, and a SUCCESS status is returned. If the customer cancels the order, the Order Token and CANCELLED status are returned. We recommend that you display the Cashtag to the customer on the review or confirmation page. This is an example event object:

```JavaScript

event: {
    "data": {
        "status": "SUCCESS",
        "cashtag": "$CASHTAG_PLACEHOLDER",
        "orderToken": "ORDER_TOKEN_PLACEHOLDER",
    }
}
```

<Info title="Cashtags are returned based on the environment">
  * **Sandbox:** The Cash App Afterpay Sandbox always returns the Cashtag: `$CASHTAG_C_TOKEN`.
  * **Production:** In production, each customer's actual Cashtag is returned.
</Info>

6. Depending on the payment flows you use for Cash App Afterpay, you follow the same process to complete an order. Either call [Auth](/cash-app-afterpay/guides/api-development/api-quickstart/deferred-capture) or [Direct Capture](/cash-app-afterpay/guides/api-development/api-quickstart/immediate-capture). You receive an APPROVED or DECLINED status from Cash App Afterpay once the Auth or Direct Capture API has been completed.

## Mobile Redirection

On Mobile, instead of a QR code, the customer is redirected to the Cash App. When the customer approves, they are returned to the URL specified in the `redirectConfirmUrl` in the Create Checkout call. This can be the same page where the Cash App Pay button is rendered e.g. merchant.com/checkout, or a new page for example, `merchant.com/review`

<Tip title="Query Params can be added to the redirectConfirmURL">
  If you want to determine if the page is loading as a result of redirect from the Cash App, you can add a query param to your redirectConfirmURL. e.g. merchant.com/checkout?cashapppay=true
</Tip>

<Info title="The redirectCancelURL is not used by Cash App Pay">
  On mobile, the customer is always redirected to the redirectConfirmUrl for approved and declined flows.
</Info>

The page the `redirectConfirmUrl` points to should initialize afterpay.js and define the below `onComplete` callback on page load:

```JavaScript

function onPageLoad () {
    var cashAppPayListenerOptions = { 
        onComplete: function(event) {
          const { status, cashtag, orderToken} = event.data;
        },
        /* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */
           eventListeners: {
                "CUSTOMER_INTERACTION": ({ isMobile }) => {
                    console.log(`CUSTOMER_INTERACTION`)
                    if (isMobile) {
                        // captureMobileMetrics()
                    } else {
                        // captureDesktopMetrics()
                    };
                },
                "CUSTOMER_REQUEST_DECLINED": () => {
                    console.log(`CUSTOMER_REQUEST_DECLINED`)
                },
                 "CUSTOMER_REQUEST_APPROVED": () => {
                    console.log(`CUSTOMER_REQUEST_APPROVED`)
                },
                "CUSTOMER_REQUEST_FAILED": () => {
                    console.log(`CUSTOMER_REQUEST_FAILED`)
                }
            }
      }

    AfterPay.initializeCashAppPayListeners({countryCode: "US", cashAppPayListenerOptions});
}
```

## Restarting Cash App Pay for a New Checkout Request

<Info>
  To implement this functionality, you must be using 

  [advanced rendering](#advanced-rendering-control)

  .
</Info>

### After checkout completion

After a successful checkout, the customer may visit another page, and then return to the checkout page to place an order without refreshing the page. Or in another scenario, you may want to provide an upsell immediately after the customer completes the checkout.

When you need to take a new order with Cash App Pay, you can call `AfterPay.restartCashAppPay`.

```js
AfterPay.restartCashAppPay()
AfterPay.renderCashAppPayButton()
```

When restarted, AfterPay.js "forgets" all previous authorizations and previously charged amounts. It also removes all Cash App Pay UI (for example, the Cash App Pay button, QR code modal, or approved Cashtag).

We recommend that in a single page app, you call `AfterPay.restartCashAppPay` whenever the customer leaves the checkout page. When restarting at the exit of each page, if a customer comes back to the checkout page, your initialization flow works as normal. The customer never sees the QR code for a previous customer request.

### Before checkout completion

In some cases, the payment button must be re-rendered and re-initialized without a successful checkout. For example, if a customer selects Cash App Pay, switches to a different payment method, and then re-selects Cash App Pay.

When a customer re-selects Cash App Pay, call `AfterPay.renderCashAppPayButton` to re-render the button. Next, restart Cash App Pay by calling `AfterPay.restartCashAppPay`.

```js
AfterPay.restartCashAppPay()
AfterPay.renderCashAppPayButton()
```

Since the original checkout token is unused, you can use that token with `AfterPay.initializeForCashAppPay(...)`.

## Payment Refunds with Cash App

Cash App Pay purchase and refund flows follow the standard Cash App Afterpay payment refund and void processes.

However, if there is an error when refunding a Cash App pay order, additional information will be supplied in the payload. See the example code below to see this in action.

**Example Code**

```
{
"errorCode": "declined",
"errorId": "ERROR_ID_PLACEHOLDER",
"message": "Cash App declined refund request (permanent decline): PAYMENT_PROCESSING_ERROR REFUND_DECLINED_OTHER  Refund could not be created.",
"httpStatusCode": 422
}
```

<Info>
  You can find a complete list of Cash App Pay error codes [here](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference).
</Info>

## Settlement with Cash App

All payment resolution is handled by Cash App Afterpay. Your settlement information differentiates between Cash App Afterpay and Cash App sales.

## Add Your Logo to the QR Code Scanner

Add your company or organization's logo to the QR code pop-up that appears during Cash App Pay checkout. You host this logo, send us its URL and we place it next to the QR code. See an example in the picture below:

![qr-code-afterpay-resized.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/qr-code-afterpay-resized.png)

To do this:

1. Host your logo with its own URL. An appropriate logo must be:

* At least 256 x 256 pixels in size

* No larger than a 2MB file size

* A square logo, because other shapes get distorted.

* Produced with spacing/padding around the logo image, so that no part of the logo is cut-off when it is displayed

* In a format of either .png, .jpg, or .jpeg

2. Contact your Cash App Afterpay sales contact or Cash App Afterpay merchant services representative and send them the logo URL.

3. We (Cash App Afterpay) will ensure your logo appears next to the Cash App Pay QR code.

A brand logo is not necessary for Cash App Pay to work, although the co-branding enhances the customer experience at checkout. Your brand logo is required to pass certification testing.

## Advanced Rendering Control

As standard, we provide a fully managed and branded UI that includes a Cash App Pay button.

In some situations you may want advanced controls. For example, you may want to validate information a customer has given during checkout before the transaction continues. When `AfterPay.renderCashAppPayButton` is called, a begin method is returned through the `onBegin` callback for you to call when you're ready.

### Create Your Custom Button

You have two choices - to use JavaScript to create the custom button, or to use HTML direct.

**JavaScript**

```JavaScript
function createCustomButton() {
  // Create custom button
  const cashAppPayCustomButton = document.createElement('button');
  cashAppPayCustomButton.classList.add('btn', 'cash-app-pay-custom-button');
  cashAppPayCustomButton.textContent = "Continue with";

  // Attach cash app pay logo to button
  const cashAppPayLogo = document.createElement('cash-app-pay-logo');
  cashAppPayCustomButton.appendChild(cashAppPayLogo);
  document.getElementById('cash-app-pay').after(cashAppPayCustomButton);
}

```

**HTML**

```HTML
<button class="btn cash-app-pay-custom-button">
  Continue with<cash-app-pay-logo></cash-app-pay-logo>
</button>
```

The `<cash-app-pay-logo>` element renders a Cash App Pay logo. You can use this logo on your "choose a payment method page," or to enhance your checkout button.

### Initialize the Authorization Flow when Ready

You may want to use a specific button in your checkout experience for consistency across payment methods. When the manage option is `false`, you can also set the button option to `false`. This stops a Cash App Pay button from being rendered. You can now provide your own button and manage the authorization flow.

```JavaScript
// Attach event listener to the custom button described in the previous section
function addEventListenerToCashAppPayButton(func) {
  const customButton = document.querySelector('.cash-app-pay-custom-button')
  customButton.addEventListener('click', func);
}

// Initialize the CashAppPay flow
// This can be by itself or within the onBegin callback from renderCashAppPayButton 
function initializeForCashAppPay(token) {
  var cashAppPayOptions = {
    onComplete: function(event) {
      console.log(`onComplete: ${JSON.stringify(event.data, null, 4)}`);
      var { cashtag } = event.data;
      document.querySelector('.cash-app-pay-custom-button').setAttribute('hidden', true); // hide the button
      var cashAppPayCustomer = document.querySelector('cash-app-pay-customer');
      cashAppPayCustomer.setAttribute('cashtag', cashtag);
      cashAppPayCustomer.removeAttribute('hidden'); // show the cashtag
    },
    /* Optional event listeners */
    eventListeners: {
      "CUSTOMER_INTERACTION": ({ isMobile }) => {
        console.log(`CUSTOMER_INTERACTION is on Mobile: ${isMobile}`)
      },
      "CUSTOMER_REQUEST_DECLINED": () => {
        console.log(`CUSTOMER_REQUEST_DECLINED`)
      },
      "CUSTOMER_REQUEST_APPROVED": () => {
        console.log(`CUSTOMER_REQUEST_APPROVED`)
      },
      "CUSTOMER_REQUEST_FAILED": () => {
        console.log(`CUSTOMER_REQUEST_FAILED`)
      },
      "CUSTOMER_DISMISSED": () => {
        console.log(`CUSTOMER_DISMISSED`)
      }
    }
  }

  AfterPay.initializeForCashAppPay({
    countryCode: "US",
    token,
    cashAppPayOptions
  });
}

// Load PayKit and render the CashAppPayButton without making any additional API calls. Token from createCheckout is not required.
function renderCashAppPayButton() {
  var cashAppPayButtonOptions = {
    button: false, // button set to false prevents a Cash App Pay button from being rendered so you can use your own custom button
    manage: false, // when the manage option is false, a begin function will be returned for merchant to call when they're ready
    onBegin: function({ begin }) {
      addEventListenerToCashAppPayButton(async (event) => {
        event.preventDefault();
        const token = await createCheckout(true);
        initializeForCashAppPay(token);
        begin();
      });
    },
  }
  //This allows you to render the button without a token
  AfterPay.renderCashAppPayButton({
    countryCode: "US",
    cashAppPayButtonOptions
  });
}
```

## Troubleshooting

### CSP - Content Security Policy

If you want to use Cash App Pay and have a CSP (Content Security Policy), please ensure that the CSP whitelists paykit's `pay.css` file.

This whitelisting must apply equally to both the production and sandbox versions of Cash App Pay.

---

# Cash App Pay on file

## Overview

Cash App Pay on file allows customers to save their Cash App accounts with specific merchants. This makes it easy for merchants to take Cash App Pay payments and for buyers to make Cash App Pay payments.

Merchants can take a payment with the customer's prior approval. Customers can authorize merchants to charge them in the future, without having to go through a Cash App payment flow.

This setup allows for smooth, more convenient payment experiences and enables various use-cases such as frequent purchases or recurring subscriptions. See the [Overview of Cash App Pay on file](#overview-of-cash-app-pay-on-file) below.

## Terminology

* **Cash App Pay:** A digital payment method where customers can make payments with their Cash App account

* **Grant:** A payment token associated with a specific customer that merchants can use to initiate payments. Grants can be scoped to different payment methods (Cash App Afterpay, Cash App Pay) and can be consumed one or more times (one-time, on file)

* **[\$Cashtag:](https://cash.app/help/3123-what-is-a-cashtag)** A publicly-accessible, unique identifier (username) for individuals and businesses using Cash App. \$Cashtags can be changed up to three times for each Cash App account

* **Customer ID:** A non-public, unique identifier for developers to identify Cash App accounts. Customer ID is not accessible to Cash App customers and will not change if the associated \$cashtag is updated

## Common Uses of Cash App Pay on file

There are many common uses of Cash App Pay on file, several include:

* **Ecommerce Retailers:** Ecommerce merchants offer Cash App Pay on file to facilitate faster checkouts and enable more delightful payment experiences for their customers. It can also reduce cart abandonment, increase average transaction value, and boost sales

* **Subscription Services:** These are for merchants who offer goods and services that need regular payments, such as monthly subscriptions or recurring orders. You can use Cash App Pay on file to receive a customer payment during each billing cycle. This setup reduces the need for a manual payment each time, which allows for uninterrupted service and improved cash flow

* **Pre-orders:** Pre-orders allow customers to order products before they are released or restocked. Cash App Pay on file provides flexibility for merchants and empowers them to decide when and how to charge customers after a customer has placed a pre-order

* **Hospitality and Rentals:** Hospitality and rental merchants typically use Cash App Pay on file to cover advanced reservations and incidental charges such as room service

## Overview of Cash App Pay on file

Here is an overview of the Cash App Pay on file process:

1. **Storing Cash App Pay on file:** First, customers must successfully link their Cash App account and authorize merchants to store Cash App Pay on file on their behalf. Once successfully completed, merchants have access to a Cash App Pay on file grant and the customer's associated \$cashtag and customer ID.

2. **Taking Payments with Cash App Pay on file:** Once a Cash App Pay on file grant is approved and active, merchants can use the grant to initiate Cash App Pay payments on behalf of the customer.

3. **Managing Cash App Pay on file:** After a customer successfully links their Cash App account with a specific merchant, they may take specific actions. These actions include updating their \$cashtag or revoking their Cash App Pay on file grant. When these actions occur, it is important for merchants to get these updates and update relevant Cash App Pay on file details for customers.

### Pros and Cons of Cash App Pay on file

Storing Cash App Pay on file is standard practice for many merchants, but there are benefits and drawbacks to consider:

#### Pros

* **Increased Customer Convenience:** Merchant checkout is quicker and easier for returning customers as they can save Cash App Pay on file once and use it for subsequent payments. This can lead to more sales opportunities, lower cart abandonment, increased average transaction value, and more

* **Improved Customer Transparency:** Customers can track and manage merchants they have linked their Cash App account with directly within Cash App. Specifically, customers can unlink Cash App Pay on file tokens with specific merchants to prevent future unwanted payments. Fewer unwanted payments mean fewer refunds and chargebacks

* **Stronger Integration Resilience:** Cash App Pay on file customers only link to their Cash App account once, whereas one-time payments require customers to link their Cash App account for each payment. Integration issues that affect the Cash App linking process will not affect customers who have already successfully stored Cash App Pay on file with a particular merchant

#### Cons

* **Managing Cash App Pay Updates:** Merchants need to keep track of Cash App Pay on file expirations and updates. Failing to update Cash App Pay information on time can lead to declined payments and interrupted service. This may affect customer relationships

## How Cash App Pay on file Works in Detail

### Storing Cash App Pay on file

To store Cash App Pay on file, merchants first need to retrieve their Cash App Pay brand ID. Use the [Retrieve Mapping](/cash-app-afterpay/api-reference/reference/configuration/get-configuration-mappings) endpoint for this task:

#### Example Response

```JavaScript
[ 
  { 
    "name": "default", 
    "externalBrandId": "BRAND_xxxxxxxxxx" 
  } 
]
```

<Note>The Retrieve Mapping API response calls the brand ID `externalBrandId` whereas in the front-end JavaScript below, the `externalBrandId` is called `cashAppBrandId`.</Note>
Once the brand ID has been retrieved, merchants should initialize `Afterpay.js` for a Cash App on file grant request. The `cashAppBrandId` is set to the brand ID retrieved previously.

**Example code:**

```JavaScript
function initializeForCashAppOnFileGrant() { 
  var cashAppPayOnFileOptions = { 
    button: false, // set to false if using custom button 
    onComplete: function(event) { 
      const { cashtag, expiresAt, grantId, id } = event.data; 
      console.log("Data object: ", event.data); 
      console.log("Cashtag: ", cashtag); 
      console.log("ExpiresAt: ", expiresAt); 
      console.log("GrantId: ", grantId); 
      console.log("Id: ", id); }, 
    redirectUrl: "https://www.example.com", // where mobile customers should be redirected to 
    cashAppBrandId: "BRAND_xxxxxxxxxx" 
  } 

  AfterPay.initializeForCashAppOnFileGrant({ 
    countryCode: "US", 
    cashAppPayOnFileOptions 
  }); 
}
```

Once the customer successfully links their Cash App account, the `onComplete` callback returns with the Cash App Pay on file grant, together with  the associated customer's \$cashtag and customer ID. Merchants should store this data for future use.

### Suggested copy for Cash App Pay on file disclaimer

For best practice, Cash App recommends you add the following disclaimer wherever customers can store Cash App Pay on file:

*By continuing, you authorize `{{Merchant Name}}` to debit your Cash App account for this payment and future payments in accordance with `{{Merchant Name}}`'s terms, until this authorization is revoked. You can change this authorization anytime in your Cash App Settings.*

## Taking Payments with Cash App Pay on file

1. To initiate a Cash App Pay on file payment, merchants must use a valid Cash App Pay on file grant and create a new Cash App Afterpay Checkout with the `isCashAppPay: true` parameter.

2. Use the Create Checkout endpoint to generate a checkout token. Then use this checkout token and grant ID to authorize a new payment via the direct capture or auth endpoint.

<Note>
  Customers do not need to complete the checkout flow for new payments once an on file grant has been generated and is active.
</Note>

## Storing Cash App Pay on file within Checkout flow

This flow is useful if a customer is completing a merchant's checkout flow while also attempting to store their Cash App Pay on file. The flow enables merchants to complete the store Cash App Pay on file and take payments with Cash App Pay on file in a more streamlined way. Do the following:

1. Call the `Create Checkout` endpoint and add the `isCashAppPay: true` parameter.

2. Use the token in combination with the Standard Checkout flow, but call `AfterPay.initializeForCashAppPay` instead of Cash App Afterpay. Include the `requestOnFileGrant: true` within `cashAppPayOptions` for `Afterpay.initializeForCashAppPay`.

3. Store the Cash App Pay on file grant, \$cashtag, and customer ID returned in the `onComplete` callback.

4. Call the [Auth](/cash-app-afterpay/api-reference/reference/payments/auth) or [Direct Capture](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment) endpoints and make sure to include the Cash App Pay on file grant in the request.

Example code:

```javascript
function initAfterPay() { 
  var cashAppPayOptions = { 
    requestOnFileGrant: true, 
    button: { size: 'small', // "medium" | "small" width: 'full', // "full" | "static" theme: 'dark', // "dark" | "light" shape: 'round' // "round" | "semiround" }, 
    redirectUrl: window.location.href, // where mobile customers should be redirected to 
    onComplete: function(event) { 
      const { cashtag, expiresAt, grantId, id, token } = event.data; 
      console.log("Data object: ", event.data); 
      console.log("Cashtag: ", cashtag); 
      console.log("ExpiresAt: ", expiresAt); 
      console.log("GrantId: ", grantId); 
      console.log("Id: ", id); 
      console.log("Token: ", token); }, /* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */ 
  eventListeners: { 
    "CUSTOMER_INTERACTION": ({ isMobile }) => { 
      console.log(`CUSTOMER_INTERACTION`) 
      if (isMobile) { // captureMobileMetrics() } 
      else { // captureDesktopMetrics() } }, 
        "CUSTOMER_REQUEST_DECLINED": () => { console.log(`CUSTOMER_REQUEST_DECLINED`) }, 
        "CUSTOMER_REQUEST_APPROVED": () => { console.log(`CUSTOMER_REQUEST_APPROVED`) }, 
        "CUSTOMER_REQUEST_FAILED": () => { console.log(`CUSTOMER_REQUEST_FAILED`) } } } ​ 
  AfterPay.initializeForCashAppPay({ countryCode: "US", token: "ORDER_TOKEN_PLACEHOLDER", cashAppPayOptions }); 
}
```

## Managing Cash App Pay on file

Once a customer has authorized a Cash App Pay on file grant, merchants should ensure they implement the following features. These features ensure optimal Cash App Pay on file functionality:

* **Revoke Cash App Pay on file grant via Merchant:** Customers should be able to revoke their Cash App Pay on file grant directly within the merchant account settings or the merchant checkout flow. This ensures that on file grants are deactivated once they are no longer needed. It  builds customer trust as customers can manage their payment method availability directly with the merchant, versus making changes within Cash App

  * Use the [**Revoke Grant**](/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/revoke-grant) endpoint to revoke an active Cash App Pay on file grant when a customer unlinks their Cash App Pay on file

* **Revoke Cash App Pay on file grant via Cash App:** Customers can revoke their Cash App Pay on file grants with specific merchants within their Cash App settings. Therefore, merchants should subscribe to these events and unlink Cash App Pay on file for customers who have unlinked their on file grants within Cash App

  * Use the [**Event: Grant Updated**](/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/schemas/grant-status-updated) webhook to remove Cash App Pay on file grants that were unlinked within Cash App

* **Cash App Pay Updates:** Customers can make changes to their Cash App account details such as updating their \$cashtag. Also, on file grants expire after 10 years. Therefore, it is important that merchants subscribe to Cash App Pay grant updates, and keep their own records up to date

  * Use the [**Event: Grant Status Updated**](/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/schemas/grant-status-updated) webhook to subscribe to Cash App Pay updates associated with specific Cash App Pay on file grants

  * Use the [**Retrieve Grant**](/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/retrieve-grant) endpoint to retrieve the current state of Cash App Pay on file grants

---

# Retrieve Cash App Pay Grant

POST https://global-api-sandbox.afterpay.com/v2/grants/retrieve
Content-Type: application/json

Retrieves a Cash App Pay customer grant by the ID of the customer that approved it and its own ID.

Reference: https://developers.cash.app/cash-app-afterpay/guides/api-development/add-cash-app-pay-to-your-site/retrieve-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve Grant
  version: endpoint_.retrieve-grant
paths:
  /v2/grants/retrieve:
    post:
      operationId: retrieve-grant
      summary: Retrieve Grant
      description: >-
        Retrieves a Cash App Pay customer grant by the ID of the customer that
        approved it and its own ID.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: Accept
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrieve-grant_Response_200'
        '401':
          description: Unauthenticated
          content: {}
        '403':
          description: Unauthorized
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveGrantRequest'
components:
  schemas:
    RetrieveGrantRequest:
      type: object
      properties:
        customerId:
          type: string
          description: ID of the customer that approved the customer grant.
        grantId:
          type: string
          description: ID of the customer grant to retrieve.
      required:
        - customerId
        - grantId
    CashGrantIntent:
      type: string
      enum:
        - value: ON_FILE
        - value: ONE_TIME
    CashGrantType:
      type: string
      enum:
        - value: CASHAPP
    CashGrantDetailsStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: EXPIRED
        - value: CONSUMED
        - value: REVOKED
    CashGrantDetailsCashapp:
      type: object
      properties:
        customerId:
          type: string
        cashtag:
          type: string
          description: >-
            A publicly-accessible, unique identifier (username) for individuals
            and businesses using Cash App.
      required:
        - customerId
        - cashtag
    CashGrantDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CashGrantDetailsStatus'
          description: >
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        cashapp:
          $ref: '#/components/schemas/CashGrantDetailsCashapp'
        createdAt:
          type: string
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updatedAt:
          type: string
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expiresAt:
          type: string
          description: >
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - status
        - cashapp
        - createdAt
        - updatedAt
        - expiresAt
    CashGrant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this grant issued by Cash App.
        intent:
          $ref: '#/components/schemas/CashGrantIntent'
          description: Either ON_FILE or ONE_TIME
        type:
          $ref: '#/components/schemas/CashGrantType'
          description: CASHAPP for all Cash App Pay transactions
        details:
          $ref: '#/components/schemas/CashGrantDetails'
      required:
        - id
        - intent
        - type
        - details
    retrieve-grant_Response_200:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/CashGrant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/retrieve"

payload = {
    "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/retrieve';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"customerId":"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY","grantId":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/retrieve"

	payload := strings.NewReader("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/retrieve")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/retrieve")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/retrieve', [
  'body' => '{
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/retrieve");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/retrieve")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Revoke Cash App Pay Grant

POST https://global-api-sandbox.afterpay.com/v2/grants/revoke
Content-Type: application/json

Revokes a Cash App Pay customer grant by the ID of the customer that approved it and its own ID.

Reference: https://developers.cash.app/cash-app-afterpay/guides/api-development/add-cash-app-pay-to-your-site/revoke-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Revoke Grant
  version: endpoint_.revoke-grant
paths:
  /v2/grants/revoke:
    post:
      operationId: revoke-grant
      summary: Revoke Grant
      description: >-
        Revokes a Cash App Pay customer grant by the ID of the customer that
        approved it and its own ID.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: Accept
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/revoke-grant_Response_200'
        '401':
          description: Unauthenticated
          content: {}
        '403':
          description: Unauthorized
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveGrantRequest'
components:
  schemas:
    RetrieveGrantRequest:
      type: object
      properties:
        customerId:
          type: string
          description: ID of the customer that approved the customer grant.
        grantId:
          type: string
          description: ID of the customer grant to retrieve.
      required:
        - customerId
        - grantId
    CashGrantIntent:
      type: string
      enum:
        - value: ON_FILE
        - value: ONE_TIME
    CashGrantType:
      type: string
      enum:
        - value: CASHAPP
    CashGrantDetailsStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: EXPIRED
        - value: CONSUMED
        - value: REVOKED
    CashGrantDetailsCashapp:
      type: object
      properties:
        customerId:
          type: string
        cashtag:
          type: string
          description: >-
            A publicly-accessible, unique identifier (username) for individuals
            and businesses using Cash App.
      required:
        - customerId
        - cashtag
    CashGrantDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CashGrantDetailsStatus'
          description: >
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        cashapp:
          $ref: '#/components/schemas/CashGrantDetailsCashapp'
        createdAt:
          type: string
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updatedAt:
          type: string
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expiresAt:
          type: string
          description: >
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - status
        - cashapp
        - createdAt
        - updatedAt
        - expiresAt
    CashGrant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this grant issued by Cash App.
        intent:
          $ref: '#/components/schemas/CashGrantIntent'
          description: Either ON_FILE or ONE_TIME
        type:
          $ref: '#/components/schemas/CashGrantType'
          description: CASHAPP for all Cash App Pay transactions
        details:
          $ref: '#/components/schemas/CashGrantDetails'
      required:
        - id
        - intent
        - type
        - details
    revoke-grant_Response_200:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/CashGrant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/revoke"

payload = {
    "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/revoke';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"customerId":"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY","grantId":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/revoke"

	payload := strings.NewReader("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/revoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/revoke")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/revoke', [
  'body' => '{
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/revoke");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/revoke")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Event: grant.status.updated

POST 

**When is this event triggered?**

This event is triggered when a Cash App Pay grant status has been updated.

Reference: https://developers.cash.app/cash-app-afterpay/guides/api-development/add-cash-app-pay-to-your-site/grant-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: grant.status.updated'
  version: subpackage_grants.grantStatusUpdated
webhooks:
  grant-status-updated:
    post:
      operationId: grant-status-updated
      summary: 'Event: grant.status.updated'
      description: >-
        **When is this event triggered?**


        This event is triggered when a Cash App Pay grant status has been
        updated.
      tags:
        - subpackage_grants
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `grant.status.updated` for
                    this event.
                eventId:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                grant:
                  $ref: '#/components/schemas/CashGrant'
                timestamp:
                  type: string
                  description: When the webhook event was created
              required:
                - type
                - eventId
                - grant
                - timestamp
components:
  schemas:
    CashGrantIntent:
      type: string
      enum:
        - value: ON_FILE
        - value: ONE_TIME
    CashGrantType:
      type: string
      enum:
        - value: CASHAPP
    CashGrantDetailsStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: EXPIRED
        - value: CONSUMED
        - value: REVOKED
    CashGrantDetailsCashapp:
      type: object
      properties:
        customerId:
          type: string
        cashtag:
          type: string
          description: >-
            A publicly-accessible, unique identifier (username) for individuals
            and businesses using Cash App.
      required:
        - customerId
        - cashtag
    CashGrantDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CashGrantDetailsStatus'
          description: >
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        cashapp:
          $ref: '#/components/schemas/CashGrantDetailsCashapp'
        createdAt:
          type: string
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updatedAt:
          type: string
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expiresAt:
          type: string
          description: >
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - status
        - cashapp
        - createdAt
        - updatedAt
        - expiresAt
    CashGrant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this grant issued by Cash App.
        intent:
          $ref: '#/components/schemas/CashGrantIntent'
          description: Either ON_FILE or ONE_TIME
        type:
          $ref: '#/components/schemas/CashGrantType'
          description: CASHAPP for all Cash App Pay transactions
        details:
          $ref: '#/components/schemas/CashGrantDetails'
      required:
        - id
        - intent
        - type
        - details

```

---

# Shop Directory

The Cash App Afterpay shop directory provides thousands of high-quality leads to our merchant partners every day.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-afterpay/assets/images/Afterpay-Shop-Directory.png" alt="Cash App Afterpay-Shop-Directory" noZoom />

## Get Your Store on the Shop Directory

Upload your images to The Hub [here](https://hub.us.afterpay.com/us).

Having trouble accessing the Hub? Use the [Shop Directory form](https://help.business.afterpay.com/hc/en-au/requests/new?ticket_form_id=6107519252505) to contact us. Please allow 72 hours for your request to be processed.

## Shop Directory assets specifications

### Company logo

A .png file without a background, width and height between 500 and 500 px, max file size 1MB.
Black and White Logo and transparent background.

### Main image

A .jpg or .jpeg file, width and height between 500 and 500 px, max file size 1MB.
We do not accept images with text or inappropriate content to be uploaded as the main image in Shop Directory.

### Store details & Categories

A short description to summarize your store.

Select categories (up to five) - cCategory lists will vary depending on region.
To ensure that merchants are accurately categorized for our customers on the shop directory, we are currently only allowing merchants to pick up to five categories to be featured in at this time.

Need help formatting your assets? Visit our [help article.](https://help.business.afterpay.com/hc/en-au/articles/4708318101529-I-am-a-merchant-how-do-I-get-into-the-Afterpay-shop-directory-)

<Note>
  If you do not have a design resource to resize an image in-house, then you can send us a large image and we will resize it for you. The same applies for logos, if you do not have a vector image, then a large jpeg or png is fine.
</Note>

Cash App Afterpay makes all determinations about which merchants are displayed in the Shop Directory.

### In-store Location Updates:

Please use the [Upload Locations Template](https://help.business.afterpay.com/hc/en-au/article_attachments/10004984195353/Upload_Locations_Template.xlsx) if your request includes in-store location updates.

Upload a file via the [Shop Directory form](https://help.business.afterpay.com/hc/en-au/requests/new?ticket_form_id=6107519252505) with Store Name, Store Numbers, and Addresses of all the physical stores

---

# Cash App Afterpay API introduction

The Cash App Afterpay API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). The API uses predictable, resource-oriented URLs and uses HTTP status codes to indicate errors.

* All communication must use TLS 1.2 or higher.
* The API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence), which guarantees that if a request is retried, the operation is performed only once. This is especially important for partial refunds.
  <Note>
    Afterpay recommends using UUIDs as `requestId` values. For most endpoints, requests with the same `requestId` will return the same response for up to 24 hours. Refund requests are an exception — they support idempotency for longer than 24 hours.
    If an idempotent request returns an HTTP 409, it means the original request is still being processed. Retry the request with the same requestId until a different response is returned.
  </Note>
* API call response times can vary, especially when requests rely on downstream banking networks. All idempotent resources can be safely retried if a timeout occurs.
* All dates are represented in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, and are stored and returned in UTC. You can provide dates in UTC (e.g. `2025-01-01T13:25:00Z`) or with a time zone offset (e.g. `2025-01-01T23:25:00+10:00` for AEST).

***

## Environments

* **Production**: `https://global-api.afterpay.com`
* **Sandbox:** `https://global-api-sandbox.afterpay.com`

<Note>
  Existing merchant using region-specific endpoints (e.g. `https://api.us.afterpay.com`), can continue using them for their current region.
</Note>

***

## Pagination

The List Payment endpoint supports pagination using the `includeNextLink` query parameter.

### Request parameters

| Name              | Type    | Description                                                                                                     |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `includeNextLink` | boolean | Return a modified pagination object which includes a url to return the next page. The default value is `false`. |

### Response

| Field          | Type    | Description                                                                                                                |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `limit`        | integer | The number of results that this page was limited to.                                                                       |
| `totalResults` | integer | The total number of results matching the query. If greater than `limit`, one or more results were excluded from this page. |
| `nextPageUrl`  | string  | A URL to return the next page (empty if there are no more results).                                                        |
| `results`      | array   | A page of matching results (may be a subset of the total).                                                                 |

### Example request

```cURL
curl https://global-api-sandbox.afterpay.com/v2/payments?includeNextLink=true \
  -H 'Authorization: Basic <Base64EncodedCredentials>' \
  -H 'User-Agent: <MyUserAgent>' \
  -H 'Accept: application/json'
```

### Example response

```json
{
  "totalResults": 210,
  "limit": 20,
  "nextPageUrl":     "https://global-api-sandbox.afterpay.com/v2/payments?cursor=MjAyMTExMDlUMDUzNTI1LjI1Nlo%3D%3AMDAxLjVuNDhzbm1qNTh0ZzFkZmcwMzR2cGV2ZG1zY2ZiaTllZmVqMzRkMjl1c25mbDVnbg%3D%3D&includeNextLink=true", 
  "results": [
    ...
  ]
}
```

---

# Request headers

Merchants must send appropriate headers with all requests.

## HTTP headers

| Field Name    | Requirement | Description                                                                                   |
| ------------- | ----------- | --------------------------------------------------------------------------------------------- |
| Authorization | required    | See [Authentication](/cash-app-afterpay/api-reference/reference/introduction/authentication). |
| Content-Type  | required    | All POST and PUT requests must declare the content-type as `application/json`.                |
| User-Agent    | required    | See below.                                                                                    |
| Accept        | recommended | All requests must accept `application/json` or `*/*`.                                         |

## User-Agent header

User-Agent headers are used by the Cash App Afterpay team to identify API requests. A User-Agent header must be supplied with all Merchant API requests prior to placing any live transactions.

For example: `MyAfterpayModule/1.0.0 (E-Commerce Platform Name/1.0.0; PHP/7.0.0; Merchantname/600032000) https://merchant.example.com`

| Description          | Example Data Above                                           | Other Merchant Examples                                                                           |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Afterpay Plugin      | MyAfterpayModule/1.0.0                                       | Custom Plugin/1.0<br />Shopify Plugin/3.5.1<br />AfterpayCartridge/1.0<br />AfterpayExtension/2.9 |
| Platform             | E-Commerce Platform Name/1.0.0                               | Websphere Commerce/8.1<br />Commerce Cloud/1.1<br />Adobe Commerce (Magento)/2.3.0                |
| System Information   | PHP/7.0.0                                                    | PHP/7.2.18<br /> Ruby/2.5.3<br /> Java/8.3                                                        |
| Merchant ID          | Merchantname/600032000                                       | Merchantname/101113200<br />Merchantname/101931210                                                |
| Merchant Website URL | [https://merchant.example.com](https://merchant.example.com) | [http://www.merchantwebsite.com](http://www.merchantwebsite.com)                                  |

<Note>
  In this case the Merchant ID is your company name or organisation name followed by an eight-digit number.
</Note>

---

# Authentication

The Cash App Afterpay Online API uses two different authentication options, which are discussed below. With the exception of [Ping](/cash-app-afterpay/api-reference/reference/service-status/ping), all Online API endpoints require that one of these forms of authentication are used. Failure to correctly authenticate an API request will result in a `401 Unauthorized` response.

## Basic auth

The first authentication method is [Basic HTTP Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), a simple authentication scheme built into the HTTP protocol, as specified by [RFC 7617](https://tools.ietf.org/html/rfc7617).

### Example request

<Tabs>
  <Tab title="HTTP" language="http">
    ```http
    GET /v2/configuration HTTP/1.1
    Host: global-api-sandbox.afterpay.com
    Authorization: Basic MzI6YWJjZGVmZ2g=
    ```
  </Tab>

  <Tab title="cURL" language="curl">
    ```bash
    curl "https://global-api-sandbox.afterpay.com/v2/configuration" \
      -H 'Authorization: Basic MzI6YWJjZGVmZ2g='
    ```
  </Tab>

  <Tab title="Node.js" language="javascript">
    ```javascript
    var request = require("request");

    var options = {
      url: 'https://global-api-sandbox.afterpay.com/v2/configuration',
      headers: {
        Authorization: 'Basic MzI6YWJjZGVmZ2g='
      }
    };

    request(options, function (error, response, body) {
      if (error) throw new Error(error);

      console.log(body);
    });
    ```
  </Tab>

  <Tab title="Ruby" language="ruby">
    ```ruby
    require 'uri'
    require 'net/http'

    url = URI("https://global-api-sandbox.afterpay.com/v2/configuration")

    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Get.new(url)
    request["Authorization"] = 'Basic MzI6YWJjZGVmZ2g='

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>

  <Tab title="Python" language="python">
    ```python
    import requests

    url = "https://global-api-sandbox.afterpay.com/v2/configuration"

    headers = {
        'Authorization': "Basic MzI6YWJjZGVmZ2g="
    }

    response = requests.request("GET", url, headers=headers)

    print(response.text)
    ```
  </Tab>
</Tabs>

Consider the following example:

| Merchant ID | Secret Key |
| ----------- | ---------- |
| 32          | abcdefgh   |

<Info>
  In conventional HTTP terms, "Merchant ID" is the **username** and "Secret Key" is the **password**.
  Afterpay provides merchant accounts per region, and each merchant account has unique API credentials.
</Info>

The credentials are joined by a colon character (without any spaces), then base64-encoded.

| Plain Text  | Base64 Encoded   |
| ----------- | ---------------- |
| 32:abcdefgh | MzI6YWJjZGVmZ2g= |

The `Authorization` header can then be formed by including the word `Basic`, followed by a single space character, followed by the base64-encoded credential pair.

|              |                                         |   |
| ------------ | --------------------------------------- | - |
| Final Header | `Authorization: Basic MzI6YWJjZGVmZ2g=` |   |

<Info title="Security Notice">
  The base64-encoding of the Authorization header is unrelated to security. All HTTP headers and bodies (for both requests and responses) between the Merchant and Afterpay are encrypted with TLS. The reason for base64-encoding is solely to comply with the [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617.txt) standard, which allows non-HTTP characters and multibyte strings to be used for [Basic HTTP Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
</Info>

## Bearer tokens

The Client Credentials Authentication method is another authentication method available to merchants. It is a secure mechanism used to obtain access tokens which is defined in [RFC 6749](https://datatracker.ietf.org/doc/rfc6749/).

When using this method, a client application uses its unique credentials to fetch an access token, which enables it to access Cash App Afterpay's online APIs.

### Token URLs

Tokens are generated using separate URLs from those described in the [API environments](/cash-app-afterpay/api-reference/reference/introduction)

<Tabs>
  <Tab title="OAuth Endpoint Production">
    |             |                                                      |
    | ----------- | ---------------------------------------------------- |
    | Locations   | AU, NZ, US, CA, and UK                               |
    | Environment | `https://merchant-auth.afterpay.com/v2/oauth2/token` |
  </Tab>

  <Tab title="OAuth Endpoint Sandbox">
    |             |                                                              |
    | ----------- | ------------------------------------------------------------ |
    | Locations   | AU, NZ, US, CA, and UK                                       |
    | Environment | `https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token` |
  </Tab>
</Tabs>

### Example request

The following examples use the same credentials as the [Basic Auth](#basic-auth) section.

<Note>
  The `scopes` field mentioned below is `merchant_api_v2`, but `merchant_api_v1` may be used to access the first version of the merchant APIs.
</Note>

#### Access token request

```http
POST /v2/oauth2/token HTTP/1.1
Host: https://merchant-auth-sandbox.afterpay.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=32
&client_secret=abcdefgh
&scope=merchant_api_v2
```

```cURL
curl -X POST "https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=32&client_secret=abcdefgh&scope=merchant_api_v2"
```

```javascript
const request = require('request');

const options = {
  url: 'https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token',
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  form: {
    grant_type: 'client_credentials',
    client_id: '32',
    client_secret: 'abcdefgh',
    scope: 'merchant_api_v2'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path, { 'Content-Type' => 'application/x-www-form-urlencoded' })

request.set_form_data({
  'grant_type' => 'client_credentials',
  'client_id' => '32',
  'client_secret' => 'abcdefgh',
  'scope' => 'merchant_api_v2'
})

response = http.request(request)

puts response.body
```

```python
import requests

data = {
    'grant_type': 'client_credentials',
    'client_id': '32',
    'client_secret': 'abcdefgh',
    'scope': 'merchant_api_v2'
}

response = requests.post('https://merchant-auth-sandbox.afterpay.com/v2/oauth2/token', data=data)
print(response.json())
```

### Access token response

The response to a successful authentication request includes the full JWT `access_token`. In the example below, the token is shortened for brevity.

```json
{
  "access_token": "eyJraWQiOiIwMzllNDBlMy0wYjM5LTQ3MTktOGFjNS05ZmE0OWRiMjQ3MWMiLCJhbGciOiJSUzI1NiJ9.eyJzd…",
  "scope": "merchant_api_v2/read merchant_api_v2/reverse merchant_api_v2/void merchant_api_v2/deferred_capture merchant_api_v2/capture merchant_api_v2/manage merchant_api_v2/initiate merchant_api_v2/cancel_subscription merchant_api_v2/direct_capture merchant_api_v2/refund merchant_api_v2/auth",
  "token_type": "Bearer",
  "expires_in": 86399
} 
```

<Note>
  The field `expires_in` is the time (in seconds) that the token is valid from when its generated. The token is not usable after this time elapses.
</Note>

### API requests with token

See the following example where the `access_token` field is provided in the `Authorization` header of the request to access a secure API:

```http request
GET /v2/configuration HTTP/1.1
Host: global-api-sandbox.afterpay.com
Authorization: Bearer eyJraWQiOiIwMzllNDBlMy0wYjM5LTQ3MTktOGFjNS05ZmE0OWRiMjQ3MWMiLCJhbGciOiJSUzI1NiJ9.eyJzd…
```

<Info>
  Instead of the Authorization header using a prefix of 

  `Basic`

  , the token authentication method uses 

  `Bearer`

  . Omitting this value or setting it to something else will return an HTTP status code of 

  `401 Unauthorized`
</Info>

<Info>
  Other Cash App Afterpay APIs are accessible by using the same authentication scheme as the previous example.
</Info>

---

# Errors

The Cash App Afterpay API uses conventional HTTP status codes and returns error responses in JSON format.

### HTTP status codes

| HTTP Status Codes | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| 200-299           | The request was processed successfully.                            |
| 400-499           | The request was not valid (e.g. a required parameter was missing). |
| 500-599           | The request could not be processed for an unexpected reason.       |

### Error fields

| Field          | Type    | Description                                                                                                                           |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| errorCode      | string  | The type of error returned. For example, `invalid_object`, `unsupported_currency`, or `invalid_token`.                                |
| errorId        | string  | A unique error ID.                                                                                                                    |
| message        | string  | A human-readable message which provides more details about the error. In most cases, these messages can be displayed to the customer. |
| httpStatusCode | integer | The HTTP status code.                                                                                                                 |

### Example errors

#### GET requests

With the exception of [Ping](/cash-app-afterpay/api-reference/reference/service-status/ping), which doesn't require authentication, all GET endpoints can return the following errors:

| HTTP status            | Error code           | Description                                                                                   |
| ---------------------- | -------------------- | --------------------------------------------------------------------------------------------- |
| 401 Unauthorized       | `unauthorized`       | Invalid merchant API credentials were passed in the `Authorization` header.                   |
| 405 Method Not Allowed | `method_not_allowed` | The request was made by a method other than `GET`, `HEAD`, or `OPTIONS`.                      |
| 406 Not Acceptable     | `error`              | The request included an `Accept` header for something other than `application/json` or `*/*`. |

#### POST / PUT requests

All PUT and POST endpoints can return any of the following errors:

| HTTP status                | Error code           | Description                                                                                                                          |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 400 Bad Request            | `invalid_json`       | The request body contains invalid or improperly formatted JSON.                                                                      |
| 401 Unauthorized           | `unauthorized`       | Invalid Merchant API credentials were passed in the `Authorization` header.                                                          |
| 405 Method Not Allowed     | `method_not_allowed` | The request used an unsupported HTTP method. Only `PUT` or `POST` may be allowed, depending on the endpoint. Use `OPTIONS` to check. |
| 406 Not Acceptable         | `error`              | The `Accept` header was not set to `application/json` or `*/*`.                                                                      |
| 415 Unsupported Media Type | `error`              | The request lacked a `Content-Type` header or used a value other than `application/json`.                                            |
| 500 Internal Server Error  | `error`              | Often caused by a missing or empty request body in `PUT` or `POST` requests.                                                         |

---

# Data requirements for select verticals

Depending on the goods and services you provide to customers, you may need to provide additional data in your Create Checkout payloads. If required, add this data to the optional `custom` object within the Create Checkout request payload. See data requirements below.

<Note>
  These merchant category flags are intended to provide a general understanding of the requirements across various verticals, though they may not cover all scenarios. Please note while your business may align with these verticals, all merchants must be reviewed and approved through Block's standard onboarding process. Your Delivery Manager will guide you through the specific flags needed for your integration. Block reserves the right to update merchant category requirements as needed.
</Note>

### Consumer electronics

This data is required to be present for each Item object; it will appear in the checkout's `items` array.

| Attribute             | Data Type                 | Description                                                   |
| --------------------- | ------------------------- | ------------------------------------------------------------- |
| name                  | string                    | The name of the item                                          |
| sku                   | string                    | The SKU of the item                                           |
| quantity              | integer                   | The quantity of the item ordered                              |
| pageUrl               | string                    | The URL of the item on your store’s website                   |
| imageUrl              | string                    | The URL of the item’s image on your store’s website           |
| price                 | object                    | The price of the item, containing the amount and the currency |
| categories            | array of array of strings | The category or categories that the item belongs to           |
| estimatedShipmentDate | string                    | The estimated ship date for the item                          |

**Payload structure:**

```json
"items": [
  {
    "name": "Waterproof Bluetooth Speaker",
    "sku": "12341234",
    "quantity": 1,
    "pageUrl": "https://merchant.example.com/bluetoothspeaker-354193.html",
    "imageUrl": "https://merchant.example.com/bluetoothspeaker-7378-391453-1.jpg",
    "price": {
      "amount": "100.00",
      "currency": "USD"
    },
    "categories": [
      [
        "Bluetooth",
        "Speaker",
        "Portables"]
        "Rechargeable"
      ]
      [
        "Sale",
        "Portable Speakers"
      ]
    ],
	  "estimatedShipmentDate": "2025-08-01"
  }
 ],

}
```

### Digital goods (software, applications)

| Attribute       | Data Type | Description                                                                   |
| --------------- | --------- | ----------------------------------------------------------------------------- |
| productType     | string    | The type of product.                                                          |
| productCategory | string    | The category of the product.                                                  |
| subSellerId     | string    | The ID of the sub-seller, if applicable.                                      |
| subSellerName   | string    | The name of the sub-seller of this product, if applicable.                    |
| recipientEmail  | string    | The email address of the consumer who is receiving the product.               |
| purchaseType    | string    | Whether this was a subscription or one-time purchase.                         |
| consumerTenure  | string    | Indicates whether the consumer is new or existing, or their membership level. |

**Payload structure:**

```json
"custom": {
 "productType": "Software",
 "productCategory": "Software License",
 "subSellerId": "abc123",
 "subSellerName":"Userabc123",
 "recipientEmail": "johnsmith@email.com",
 "purchaseType": "subscription",
 "consumerTenure": "membership level 1"
}
```

### Education services and courses

| Attribute      | Data Type         | Description                                                                   |
| -------------- | ----------------- | ----------------------------------------------------------------------------- |
| educationType  | string            | The type of educational service or course (e.g., course, workshop, tutoring). |
| startDate      | string (datetime) | The start date and time of the service or course.                             |
| endDate        | string (datetime) | The end date and time of the service or course.                               |
| eventLocation  | string            | Whether the service/course is online or offline.                              |
| purchaseType   | string            | Indicates whether it is a subscription-based or one-time purchase.            |
| consumerTenure | string            | Indicates whether the consumer is new or existing, or their membership level. |

**Payload structure:**

```json
"custom": {
 "educationType": "course",
 "startDate":"2022-07-10 15:00:00.000",
 "endDate":"2022-07-10 15:00:00.000",
 "eventLocation":"online",
 "purchaseType": "one-time-purchase",
 "consumerTenure": "membership level 1"
}
```

### Experience and ticket sales/events

| Attribute      | Data Type         | Description                                                                   |
| -------------- | ----------------- | ----------------------------------------------------------------------------- |
| eventName      | string            | The name of the event.                                                        |
| ticketQuantity | integer           | The number of tickets purchased.                                              |
| ticketPrice    | string            | The price of a single ticket.                                                 |
| eventDate      | string (datetime) | The date and time of the event, in timestamp format.                          |
| eventCity      | string            | The city where the event is taking place.                                     |
| eventState     | string            | The state where the event is taking place.                                    |
| eventCountry   | string            | The country where the event is taking place.                                  |
| subSellerId    | string            | The ID of the sub-seller, if applicable.                                      |
| subSellerName  | string            | The name of the sub-seller, if applicable.                                    |
| eventId        | string            | The unique identifier for the event, if applicable.                           |
| purchaseType   | string            | Whether this was a subscription or one-time purchase.                         |
| consumerTenure | string            | Indicates whether the consumer is new or existing, or their membership level. |

**Payload structure:**

```json
"custom": {
 "eventName": "Glastonbury Festival",
 "ticketQuantity": "2",
 "ticketPrice": "400.00",
 "eventDate":"2022-07-10 15:00:00.000",
 "eventCity": "Los Angeles",
 "eventState": "California",
 "eventCountry": "US",
 "subSellerId": "abc123",
 "subSellerName":"Userabc123",
 "eventId":"1234567",
 "purchaseType": "one-time-purchase",
 "consumerTenure": "membership level 1"
}
```

### Marketplaces

| Attribute      | Data Type | Description                                                                   |
| -------------- | --------- | ----------------------------------------------------------------------------- |
| subSellerId    | string    | The ID of the sub-seller.                                                     |
| subSellerName  | string    | The name of the sub-seller.                                                   |
| consumerTenure | string    | Indicates whether the consumer is new or existing, or their membership level. |

**Payload structure:**

```json
"custom": {
 "subSellerId": "abc123",
 "subSellerName":"Userabc123",
 "consumerTenure": "membership level 1"
}
```

### Musical instruments

| Attribute      | Data Type | Description                                                                   |
| -------------- | --------- | ----------------------------------------------------------------------------- |
| condition      | string    | The condition of the instrument (e.g., new, used, second-hand).               |
| consumerTenure | string    | Indicates whether the consumer is new or existing, or their membership level. |

**Payload structure:**

```json
"custom": {
  "condition": "used",
  "consumerTenure": "membership level 1"
}
```

### Services

| Attribute      | Data Type         | Description                                                                   |
| -------------- | ----------------- | ----------------------------------------------------------------------------- |
| serviceType    | string            | The type of service provided (e.g., spa, cleaning, consulting).               |
| startDate      | string (datetime) | The start date and time of the service.                                       |
| endDate        | string (datetime) | The end date and time of the service.                                         |
| eventCity      | string            | The city where the service is provided.                                       |
| eventState     | string            | The state where the service is provided.                                      |
| eventCountry   | string            | The country where the service is provided.                                    |
| consumerTenure | string            | Indicates whether the consumer is new or existing, or their membership level. |

**Payload structure:**

```json
"custom": {
 "serviceType": "spa",
 "startDate":"2022-07-10 15:00:00.000",
 "endDate":"2022-07-10 15:00:00.000",
 "eventCity": "Los Angeles",
 "eventState": "California",
 "eventCountry": "US",
 "consumerTenure": "membership level 1"
}
```

### Travel

| Attribute      | Data Type | Description                                                                   |
| -------------- | --------- | ----------------------------------------------------------------------------- |
| consumerTenure | string    | Indicates whether the consumer is new or existing, or their membership level. |
| travel.type    | string    | Type of travel (e.g., flight, hotel, car rental, transportation, etc.).       |

<Note>
  All travel transactions must use the `consumerTenure` and `travel.type` attributes. For type-specific attributes, see the tables below.
</Note>

#### Flight details

| Attribute            | Data Type         | Description                                        |
| -------------------- | ----------------- | -------------------------------------------------- |
| flight.departureDate | string (datetime) | The date and time of the flight's departure.       |
| flight.arrivalDate   | string (datetime) | The date and time of the flight's arrival.         |
| flight.departureCity | string            | The city the flight departs from.                  |
| flight.arrivalCity   | string            | The city the flight arrives at.                    |
| flight.airline       | string            | The name of the airline.                           |
| flight.class         | string            | The flight class (e.g., economy, business, first). |
| flight.passengers    | integer           | The number of passengers on the flight.            |

#### Hotel details

| Attribute           | Data Type         | Description                               |
| ------------------- | ----------------- | ----------------------------------------- |
| hotel.checkInDate   | string (datetime) | The check-in date and time at the hotel.  |
| hotel.checkOutDate  | string (datetime) | The check-out date and time at the hotel. |
| hotel.hotelCity     | string            | The city where the hotel is located.      |
| hotel.hotelName     | string            | The name of the hotel.                    |
| hotel.hotelRating   | integer           | The star rating/class of the hotel.       |
| hotel.numberOfRooms | integer           | The number of rooms booked at the hotel.  |

#### Car rental details

| Attribute                 | Data Type         | Description                                            |
| ------------------------- | ----------------- | ------------------------------------------------------ |
| carRental.pickUpDate      | string (datetime) | The date and time for picking up the rental car.       |
| carRental.dropOffDate     | string (datetime) | The date and time for dropping off the rental car.     |
| carRental.pickUpLocation  | string            | The location for picking up the rental car.            |
| carRental.dropOffLocation | string            | The location for dropping off the rental car.          |
| carRental.make            | string            | The make of the rental car (e.g., Ford).               |
| carRental.model           | string            | The model of the rental car (e.g., Fiesta).            |
| carRental.namedDriver     | string            | The name of the driver responsible for the rental car. |

#### Bus/transportation details

| Attribute         | Data Type         | Description                              |
| ----------------- | ----------------- | ---------------------------------------- |
| bus.departureDate | string (datetime) | The departure date and time for the bus. |
| bus.arrivalDate   | string (datetime) | The arrival date and time for the bus.   |
| bus.departureCity | string            | The city the bus departs from.           |
| bus.arrivalCity   | string            | The city the bus arrives at.             |
| bus.busName       | string            | The name of the bus service.             |
| bus.passengers    | integer           | The number of passengers on the bus.     |

**Payload structure:**

```json
"custom": {
  "consumer tenure": "membership level 1", 
  "travel": {
      "type":"flight",
      "flight":{
        "departureDate":"2022-07-10 15:00:00.000",
        "arrivalDate":"2022-07-17 20:00:00.000",
        "departureCity": "New York",
        "arrivalCity": "London",
        "airline": "British Airways",
        "class": "economy",
        "passengers": "2"
      },
      "hotel":{
       "checkInDate": "2022-07-10 15:00:00.000",
       "checkOutDate": "2022-07-10 15:00:00.000",
       "hotelCity": "London", 
       "hotelName": "The Grand",
       "hotelRating": "3",
       "numberOfRooms": "2",
      },
     "carRental":{
       "pickUpDate":"2022-07-10 15:00:00.000",
       "dropOffDate":"2022-07-17 20:00:00.000",
       "pickUpLocation": "M4 6JD",
       "dropOffLocation": "M4 6JD",
       "make":"Ford",
       "model":"Fiesta",
       "namedDriver": "John Smith"
      },
      "bus":{
        "departureDate":"2022-07-10 15:00:00.000",
        "arrivalDate":"2022-07-11 20:00:00.000",
        "departureCity": "Los Angeles",
        "arrivalCity": "San Francisco",
        "busName": "California Charter",
        "passengers": "12"
      }
    }
}
```

---

# Create Checkout

POST https://global-api-sandbox.afterpay.com/v2/checkouts
Content-Type: application/json

The `checkouts` endpoint is responsible for creating a new checkout and returning the associated checkout token.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/checkouts/create-checkout-1

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Checkout
  version: endpoint_.create-checkout-1
paths:
  /v2/checkouts:
    post:
      operationId: create-checkout-1
      summary: Create Checkout
      description: >
        The `checkouts` endpoint is responsible for creating a new checkout and
        returning the associated checkout token.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: Returns a token, expiry date/time, and checkout URL if successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkout-Response'
        '400':
          description: Bad Request
          content: {}
        '422':
          description: >
            | errorCode | Description |

            | --- | --- |

            | invalid_object | One or more required fields were missing or
            invalid. |

            | unsupported_payment_type | The `amount` is outside of the
            merchant's payment limits, as returned by GET Configuration. |

            | unsupported_currency | One or more Money objects contained a
            currency that differs from the merchant's account currency. |
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Checkout-Request'
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    CheckoutRequestMerchant:
      type: object
      properties:
        redirectConfirmUrl:
          type: string
        redirectCancelUrl:
          type: string
        popupOriginUrl:
          type: string
          description: >-
            The URL location from which Cash App Afterpay is initiated (required
            for express checkout). Optional for standard checkout when a
            `redirectConfirmURL` is provided.
        name:
          type: string
          description: >-
            The merchant name displayed in the Cash App Afterpay checkout flow,
            confirmation & refund emails, and the consumer portal
      required:
        - redirectConfirmUrl
        - redirectCancelUrl
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Checkout-Request:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Money'
        consumer:
          $ref: '#/components/schemas/Consumer'
        merchantReference:
          type: string
        billing:
          $ref: '#/components/schemas/Contact'
        shipping:
          $ref: '#/components/schemas/Contact'
        merchant:
          $ref: '#/components/schemas/CheckoutRequestMerchant'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        description:
          type: string
        mode:
          type: string
          default: standard
          description: |-
            Must be set to `express` to enable express checkout. 
            Allowed values: `express` `standard`
      required:
        - amount
        - consumer
    Checkout-Response:
      type: object
      properties:
        token:
          type: string
          description: Checkout token to be used to complete payment.
        expires:
          type: string
          description: >-
            The UTC timestamp of when the checkout token will expire, in ISO
            8601 format.
        redirectCheckoutUrl:
          type: string
          description: >-
            A URL that can be used to redirect the customer to the Cash App
            Afterpay screenflow directly from the merchant backend.

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/checkouts"

payload = {
    "amount": {
        "amount": "100.00",
        "currency": "AUD"
    },
    "consumer": { "email": "test@example.com" }
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/checkouts';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"amount":{"amount":"100.00","currency":"AUD"},"consumer":{"email":"test@example.com"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/checkouts"

	payload := strings.NewReader("{\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"consumer\": {\n    \"email\": \"test@example.com\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/checkouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"consumer\": {\n    \"email\": \"test@example.com\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/checkouts")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"consumer\": {\n    \"email\": \"test@example.com\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/checkouts', [
  'body' => '{
  "amount": {
    "amount": "100.00",
    "currency": "AUD"
  },
  "consumer": {
    "email": "test@example.com"
  }
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/checkouts");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"consumer\": {\n    \"email\": \"test@example.com\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "amount": [
    "amount": "100.00",
    "currency": "AUD"
  ],
  "consumer": ["email": "test@example.com"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/checkouts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Get Checkout

GET https://global-api-sandbox.afterpay.com/v2/checkouts/{token}

This endpoint retrieves an incomplete individual checkout by token.

Checkout details are only retained in this temporary format for up to 60 minutes. If a checkout token expires or has an order created against it, it can no longer be retrieved from this endpoint.
To retrieve a [Payment](../docs/ONLINE-API/Payment-object.md) record (Cash App Afterpay Order) along with its associated checkout details, see Get Payment By Token.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/checkouts/get-checkout

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Checkout
  version: endpoint_.get-checkout
paths:
  /v2/checkouts/{token}:
    get:
      operationId: get-checkout
      summary: Get Checkout
      description: >
        This endpoint retrieves an incomplete individual checkout by token.


        Checkout details are only retained in this temporary format for up to 60
        minutes. If a checkout token expires or has an order created against it,
        it can no longer be retrieved from this endpoint.

        To retrieve a [Payment](../docs/ONLINE-API/Payment-object.md) record
        (Cash App Afterpay Order) along with its associated checkout details,
        see Get Payment By Token.
      tags:
        - []
      parameters:
        - name: token
          in: path
          description: The token of the checkout to be retrieved.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: >
            Returns an object combining the [Checkout
            Request](reference/Checkouts.v2.yaml/components/schemas/Checkout-Request)
            and [Checkout
            Response](reference/Checkouts.v2.yaml/components/schemas/Checkout-Response)
            for a provided token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-checkout_Response_200'
        '404':
          description: No checkout token was provided.
          content: {}
        '412':
          description: >-
            The checkout token is invalid, expired, completed, or does not
            exist.
          content: {}
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    CheckoutRequestMerchant:
      type: object
      properties:
        redirectConfirmUrl:
          type: string
        redirectCancelUrl:
          type: string
        popupOriginUrl:
          type: string
          description: >-
            The URL location from which Cash App Afterpay is initiated (required
            for express checkout). Optional for standard checkout when a
            `redirectConfirmURL` is provided.
        name:
          type: string
          description: >-
            The merchant name displayed in the Cash App Afterpay checkout flow,
            confirmation & refund emails, and the consumer portal
      required:
        - redirectConfirmUrl
        - redirectCancelUrl
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    get-checkout_Response_200:
      type: object
      properties:
        token:
          type: string
          description: Checkout token to be used to complete payment.
        expires:
          type: string
          description: >-
            The UTC timestamp of when the checkout token will expire, in ISO
            8601 format.
        redirectCheckoutUrl:
          type: string
          description: >-
            A URL that can be used to redirect the customer to the Cash App
            Afterpay screenflow directly from the merchant backend.
        amount:
          $ref: '#/components/schemas/Money'
        consumer:
          $ref: '#/components/schemas/Consumer'
        merchantReference:
          type: string
        billing:
          $ref: '#/components/schemas/Contact'
        shipping:
          $ref: '#/components/schemas/Contact'
        merchant:
          $ref: '#/components/schemas/CheckoutRequestMerchant'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        description:
          type: string
        mode:
          type: string
          default: standard
          description: |-
            Must be set to `express` to enable express checkout. 
            Allowed values: `express` `standard`
      required:
        - amount
        - consumer

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/checkouts/token"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/checkouts/token';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/checkouts/token"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/checkouts/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/checkouts/token")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/checkouts/token', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/checkouts/token");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/checkouts/token")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Checkout-Request

<EndpointSchemaSnippet endpoint="GET /checkout-request-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "amount": {
      "amount": "100.00",
      "currency": "AUD"
    },
    "consumer": {
      "email": "test@example.com",
      "givenNames": "Joe",
      "surname": "Consumer",
      "phoneNumber": "0400 000 000"
    },
    "merchantReference": "string",
    "billing": {
      "name": "Joe Consumer",
      "line1": "Level 5",
      "line2": "390 Collins Street",
      "area1": "Melbourne",
      "region": "VIC",
      "postcode": "3000",
      "countryCode": "AU",
      "phoneNumber": "0400 000 000"
    },
    "shipping": {
      "name": "Joe Consumer",
      "line1": "Level 5",
      "line2": "390 Collins Street",
      "area1": "Melbourne",
      "region": "VIC",
      "postcode": "3000",
      "countryCode": "AU",
      "phoneNumber": "0400 000 000"
    },
    "merchant": {
      "redirectConfirmUrl": "https://example.com/checkout/confirm",
      "redirectCancelUrl": "https://example.com/checkout/cancel",
      "popupOriginUrl": "https://merchant.com/cart",
      "name": "string"
    },
    "items": [
      {
        "name": "Blue Carabiner",
        "sku": "12341234",
        "quantity": 1,
        "pageUrl": "https://merchant.example.com/carabiner-354193.html",
        "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
        "price": {
          "amount": "40.00",
          "currency": "AUD"
        },
        "categories": [
          [
            "Sporting Goods",
            "Climbing Equipment",
            "Climbing",
            "Climbing Carabiners"
          ],
          [
            "Sale",
            "Climbing"
          ]
        ],
        "estimatedShipmentDate": "2023-08-01"
      }
    ],
    "courier": {
      "shippedAt": "2025-08-24T14:15:22Z",
      "name": "USA Post",
      "tracking": "AA0000000000000",
      "priority": "STANDARD"
    },
    "taxAmount": {
      "amount": "100.00",
      "currency": "AUD"
    },
    "shippingAmount": {
      "amount": "100.00",
      "currency": "AUD"
    },
    "discounts": [
      {
        "displayName": "New Customer Coupon",
        "amount": {}
      }
    ],
    "description": "string",
    "mode": "standard"
  }
  ```
</Aside>

---

# Checkout-Response

<EndpointSchemaSnippet endpoint="GET /checkout-response-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
    "expires": "2023-08-29T00:00:00.000Z",
    "redirectCheckoutUrl": "https://portal.sandbox.afterpay.com/us/checkout/?token=005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"
  }
  ```
</Aside>

---

# Get Configuration

GET https://global-api-sandbox.afterpay.com/v2/configuration

Use this endpoint to retrieve the merchant's applicable payment limits.

A request to [Create Checkout](Checkouts.v2.yaml/paths/~1v2~1checkouts/post) may be rejected if the order amount is not between the `minimumAmount` and `maximumAmount` (inclusive).

Cash App Afterpay merchant configuration does not change frequently. For this reason, the configuration response includes Cache-Control headers to minimise network round trips when using a modern HTTP client. You should call Get Configuration on a fixed schedule, preferably once per day.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 20             |

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/configuration/get-configuration

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Configuration
  version: endpoint_.get-configuration
paths:
  /v2/configuration:
    get:
      operationId: get-configuration
      summary: Get Configuration
      description: >-
        Use this endpoint to retrieve the merchant's applicable payment limits.


        A request to [Create
        Checkout](Checkouts.v2.yaml/paths/~1v2~1checkouts/post) may be rejected
        if the order amount is not between the `minimumAmount` and
        `maximumAmount` (inclusive).


        Cash App Afterpay merchant configuration does not change frequently. For
        this reason, the configuration response includes Cache-Control headers
        to minimise network round trips when using a modern HTTP client. You
        should call Get Configuration on a fixed schedule, preferably once per
        day.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 20             |
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: >
            Returns a
            [configuration](../reference/Configuration.v2.yaml/components/schemas/Merchant-limit)
            object containing the following attributes.

            | Attribute | Type           | Description |

            |-----------|----------------| ----------- |

            | `minimumAmount`    | Money    | Minimum order amount. Note: This
            attribute may not be included if the Merchant account has no minimum
            order amount.

            | `maximumAmount`    | Money    | Maximum order amount.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant-limit'
        '401':
          description: Unauthorized
          content: {}
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    Merchant-limit:
      type: object
      properties:
        minimumAmount:
          $ref: '#/components/schemas/Money'
        maximumAmount:
          $ref: '#/components/schemas/Money'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/configuration"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/configuration';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/configuration"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/configuration")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/configuration")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/configuration', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/configuration");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/configuration")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Get Configuration Mappings

GET https://global-api-sandbox.afterpay.com/v2/configuration/mappings

To set-up Cash App Pay on file, use this endpoint to retrieve your Cash App Pay brand ID.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/configuration/get-configuration-mappings

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Configuration Mappings
  version: endpoint_.get-configuration-mappings
paths:
  /v2/configuration/mappings:
    get:
      operationId: get-configuration-mappings
      summary: Get Configuration Mappings
      description: >-
        To set-up Cash App Pay on file, use this endpoint to retrieve your Cash
        App Pay brand ID.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: Accept
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationMappings'
        '401':
          description: Unauthenticated
          content: {}
        '403':
          description: Unauthorized
          content: {}
components:
  schemas:
    ConfigurationMappings:
      type: object
      properties:
        name:
          type: string
          description: Name of the brand to be shown in Cash App next to payments.
        externalBrandId:
          type: string
          description: >-
            The brand identifier for the Cash App Afterpay <> Cash App Pay
            merchant mapping.
      required:
        - name
        - externalBrandId

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/configuration/mappings"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/configuration/mappings';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/configuration/mappings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/configuration/mappings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/configuration/mappings")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/configuration/mappings', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/configuration/mappings");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/configuration/mappings")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Merchant limits

<EndpointSchemaSnippet endpoint="GET /merchant-limit-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "minimumAmount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "maximumAmount": {
      "amount": "2000.00",
      "currency": "USD"
    }
  }
  ```
</Aside>

---

# Cash App Pay Configuration

<EndpointSchemaSnippet endpoint="GET /configuration-mappings-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "name": "Good Pour Coffee",
    "externalBrandId": "BRAND_bmxk000ucdrvljq0000yhild"
  }
  ```
</Aside>

---

# Retrieve Dispute

GET https://global-api-sandbox.afterpay.com/v2/disputes

List disputes within a date range based on certain criteria. This endpoint can be used for debugging or synchronizing the disputes from Cash App Afterpay if/when you are unable to use the webhook method.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/disputes/retrieve-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve Dispute
  version: endpoint_.retrieve-dispute
paths:
  /v2/disputes:
    get:
      operationId: retrieve-dispute
      summary: Retrieve Dispute
      description: >
        List disputes within a date range based on certain criteria. This
        endpoint can be used for debugging or synchronizing the disputes from
        Cash App Afterpay if/when you are unable to use the webhook method.
      tags:
        - []
      parameters:
        - name: order
          in: query
          description: Payment or Order token using which you can filter the list.
          required: false
          schema:
            type: integer
        - name: merchant
          in: query
          description: Merchant token using which you can filter the list.
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Dispute status using which you can filter the list.
          required: false
          schema:
            type: string
        - name: openedAfter
          in: query
          description: >-
            Filter disputes that were created on or after this timestamp
            (inclusive).
          required: false
          schema:
            type: string
            format: date-time
        - name: openedBefore
          in: query
          description: >-
            Filter disputes that were created on or before this timestamp
            (inclusive).
          required: false
          schema:
            type: string
            format: date-time
        - name: offset
          in: query
          description: Offset for the search results.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: >-
            The maximum number of records that you want returned from this
            request.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrieve-dispute_Response_200'
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: product_not_received
        - value: product_unacceptable
        - value: credit_not_processed
        - value: order_canceled
        - value: duplicate
        - value: incorrect_amount
        - value: paid_by_other_means
        - value: fraudulent
        - value: fraudulent_merchant
    DisputeStatus:
      type: string
      enum:
        - value: needs_response
        - value: under_review
        - value: won
        - value: lost
        - value: merchant_refunded
        - value: merchant_voided
    DisputeClosingReason:
      type: string
      enum:
        - value: merchant_accepted
        - value: evidence_accepted
        - value: evidence_rejected
        - value: deadline_expired
        - value: customer_cancelled
    meta:
      type: object
      properties:
        transactionAmount:
          type: string
          description: The transaction amount for the order.
        network:
          type: string
          description: >-
            The payment network used by the customer. (For example, `Visa` or
            `MasterCard`)
        networkReferenceId:
          type: string
          description: The identifier for the payment.
        orderType:
          type: string
          description: The type of order. `ONLINE` or `INSTORE`
      required:
        - transactionAmount
        - orderType
    dispute:
      type: object
      properties:
        id:
          type: string
          description: Dispute identifier
        order:
          type: string
          description: The token of the order that the dispute is for.
        amount:
          type: string
          description: The amount of the dispute
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: The reason for the dispute.
        status:
          $ref: '#/components/schemas/DisputeStatus'
          description: >-
            The current state of the dispute. Values depend on how the dispute
            state machine is modeled.
        open:
          type: boolean
          default: true
          description: '`True` if a final decision on the dispute hasn''t been made yet.'
        responseDueBy:
          type: string
          description: >-
            Deadline by which the merchant must respond to the dispute. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        createdAt:
          type: string
          description: >-
            A timestamp indicating when the dispute was created. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        openingNote:
          type: string
          description: >-
            Text from the customer describing why the dispute was opened or the
            reason for the complaint. While dispute category codes are helpful
            at informing what a merchant should present, it doesn’t provide
            reasoning behind the customer’s complaint. In some cases, this can
            help merchants troubleshoot the dispute directly with their
            customers.
        openingNoteAttachments:
          type: string
          description: >-
            Attachments to supplement the `openingNote` if the customer provided
            photos or screenshots as part of their dispute description.
        updatedAt:
          type: string
          description: >-
            Timestamp when the dispute was updated. (Epoch timestamp in seconds,
            timezone UTC +0.00)
        closingReason:
          $ref: '#/components/schemas/DisputeClosingReason'
          description: >-
            A reason indicating how the final decision on the dispute was
            reached. Recommended possible values listed in Closing Reasons.
        closingNote:
          type: string
          description: >-
            Text describing in detail how the final decision on the dispute was
            reached. This supplements the `closingReason`.
        merchantOrderId:
          type: string
          description: The identifier for the transaction on the merchant side.
        transactionDate:
          type: string
          description: >-
            The timestamp of the order created by the customer. (Epoch timestamp
            in seconds, timezone UTC +0.00)
        settlementAmount:
          type: string
          description: The settlementAmount for audit usage.
        meta:
          $ref: '#/components/schemas/meta'
          description: The extra information for merchants to match payment.
      required:
        - id
        - order
        - amount
        - reason
        - status
        - open
        - responseDueBy
        - createdAt
        - openingNote
        - closingReason
        - merchantOrderId
        - transactionDate
        - settlementAmount
    retrieve-dispute_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/dispute'
          description: >-
            An array of dispute objects that match the filter criteria in the
            request.
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes"

querystring = {"offset":"0","limit":"10"}

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes?offset=0&limit=10")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Receive Dispute

GET https://global-api-sandbox.afterpay.com/v2/disputes/{dispute_id}

Get detailed information about a dispute.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/disputes/receive-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Receive Dispute
  version: endpoint_.receive-dispute
paths:
  /v2/disputes/{dispute_id}:
    get:
      operationId: receive-dispute
      summary: Receive Dispute
      description: Get detailed information about a dispute.
      tags:
        - []
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: application/json
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute'
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: product_not_received
        - value: product_unacceptable
        - value: credit_not_processed
        - value: order_canceled
        - value: duplicate
        - value: incorrect_amount
        - value: paid_by_other_means
        - value: fraudulent
        - value: fraudulent_merchant
    DisputeStatus:
      type: string
      enum:
        - value: needs_response
        - value: under_review
        - value: won
        - value: lost
        - value: merchant_refunded
        - value: merchant_voided
    DisputeClosingReason:
      type: string
      enum:
        - value: merchant_accepted
        - value: evidence_accepted
        - value: evidence_rejected
        - value: deadline_expired
        - value: customer_cancelled
    meta:
      type: object
      properties:
        transactionAmount:
          type: string
          description: The transaction amount for the order.
        network:
          type: string
          description: >-
            The payment network used by the customer. (For example, `Visa` or
            `MasterCard`)
        networkReferenceId:
          type: string
          description: The identifier for the payment.
        orderType:
          type: string
          description: The type of order. `ONLINE` or `INSTORE`
      required:
        - transactionAmount
        - orderType
    dispute:
      type: object
      properties:
        id:
          type: string
          description: Dispute identifier
        order:
          type: string
          description: The token of the order that the dispute is for.
        amount:
          type: string
          description: The amount of the dispute
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: The reason for the dispute.
        status:
          $ref: '#/components/schemas/DisputeStatus'
          description: >-
            The current state of the dispute. Values depend on how the dispute
            state machine is modeled.
        open:
          type: boolean
          default: true
          description: '`True` if a final decision on the dispute hasn''t been made yet.'
        responseDueBy:
          type: string
          description: >-
            Deadline by which the merchant must respond to the dispute. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        createdAt:
          type: string
          description: >-
            A timestamp indicating when the dispute was created. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        openingNote:
          type: string
          description: >-
            Text from the customer describing why the dispute was opened or the
            reason for the complaint. While dispute category codes are helpful
            at informing what a merchant should present, it doesn’t provide
            reasoning behind the customer’s complaint. In some cases, this can
            help merchants troubleshoot the dispute directly with their
            customers.
        openingNoteAttachments:
          type: string
          description: >-
            Attachments to supplement the `openingNote` if the customer provided
            photos or screenshots as part of their dispute description.
        updatedAt:
          type: string
          description: >-
            Timestamp when the dispute was updated. (Epoch timestamp in seconds,
            timezone UTC +0.00)
        closingReason:
          $ref: '#/components/schemas/DisputeClosingReason'
          description: >-
            A reason indicating how the final decision on the dispute was
            reached. Recommended possible values listed in Closing Reasons.
        closingNote:
          type: string
          description: >-
            Text describing in detail how the final decision on the dispute was
            reached. This supplements the `closingReason`.
        merchantOrderId:
          type: string
          description: The identifier for the transaction on the merchant side.
        transactionDate:
          type: string
          description: >-
            The timestamp of the order created by the customer. (Epoch timestamp
            in seconds, timezone UTC +0.00)
        settlementAmount:
          type: string
          description: The settlementAmount for audit usage.
        meta:
          $ref: '#/components/schemas/meta'
          description: The extra information for merchants to match payment.
      required:
        - id
        - order
        - amount
        - reason
        - status
        - open
        - responseDueBy
        - createdAt
        - openingNote
        - closingReason
        - merchantOrderId
        - transactionDate
        - settlementAmount

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Respond to Dispute

POST https://global-api-sandbox.afterpay.com/v2/disputes/{dispute_id}
Content-Type: application/json

The Respond to the Dispute endpoint allows a merchant to submit evidence for the dispute. This is only allowed if the dispute is the state `needs_response`.

Merchants only have one opportunity to submit evidence. Once a 200 response is received, this information cannot be updated or changed.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/disputes/respond-to-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Respond to Dispute
  version: endpoint_.respond-to-dispute
paths:
  /v2/disputes/{dispute_id}:
    post:
      operationId: respond-to-dispute
      summary: Respond to Dispute
      description: >-
        The Respond to the Dispute endpoint allows a merchant to submit evidence
        for the dispute. This is only allowed if the dispute is the state
        `needs_response`.


        Merchants only have one opportunity to submit evidence. Once a 200
        response is received, this information cannot be updated or changed.
      tags:
        - []
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: application/json
          required: false
          schema:
            type: string
      responses:
        '200':
          description: When successful, returns the updated dispute object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: A unique ID given to a dispute.
                evidence:
                  $ref: '#/components/schemas/evidence'
                  description: >-
                    Evidence for the dispute. Note that there should be at least
                    one valid field.
components:
  schemas:
    evidence:
      type: object
      properties:
        productDescription:
          type: string
          description: >-
            A description of the product or service and any relevant details on
            how this was presented to the customer at the time of purchase.
        refundPolicy:
          type: string
          format: binary
          description: >-
            Token of the file upload. The merchant’s refund policy, as shown or
            provided to the customer.
        refundPolicyDisclosure:
          type: string
          description: >-
            An explanation of how and when the customer was shown or provided
            with the merchant’s refund policy prior to purchase.
        refundRefusalExplanation:
          type: string
          description: >-
            The merchant’s explanation for why the customer is not entitled to a
            refund.
        shippingDocumentation:
          type: string
          format: binary
          description: >-
            Token of the file upload. A shipping label or receipt for the
            disputed payment.
        shippingAddress:
          type: string
          description: The address to which a physical product was shipped.
        shippingDate:
          type: string
          description: >-
            In cases of physical products, the date that a physical product
            began its route to the shipping address in a clear human-readable
            format. This date should be prior to the date of the dispute.
        shippingCarrier:
          type: string
          description: >-
            In cases of physical products, the delivery service that shipped a
            physical product, such as Fedex, UPS, USPS, etc. If multiple
            carriers were used for this purchase, separate them with commas.
        shippingTrackingNumber:
          type: string
          description: >-
            The tracking number for a physical product, obtained from the
            delivery service.
        uncategorizedFile:
          type: string
          format: binary
          description: >-
            Token of the file upload. Additional file that’s not in any of the
            categories above.
        uncategorizedText:
          type: string
          description: Any additional text deemed relevant by the merchant.
    DisputeReason:
      type: string
      enum:
        - value: product_not_received
        - value: product_unacceptable
        - value: credit_not_processed
        - value: order_canceled
        - value: duplicate
        - value: incorrect_amount
        - value: paid_by_other_means
        - value: fraudulent
        - value: fraudulent_merchant
    DisputeStatus:
      type: string
      enum:
        - value: needs_response
        - value: under_review
        - value: won
        - value: lost
        - value: merchant_refunded
        - value: merchant_voided
    DisputeClosingReason:
      type: string
      enum:
        - value: merchant_accepted
        - value: evidence_accepted
        - value: evidence_rejected
        - value: deadline_expired
        - value: customer_cancelled
    meta:
      type: object
      properties:
        transactionAmount:
          type: string
          description: The transaction amount for the order.
        network:
          type: string
          description: >-
            The payment network used by the customer. (For example, `Visa` or
            `MasterCard`)
        networkReferenceId:
          type: string
          description: The identifier for the payment.
        orderType:
          type: string
          description: The type of order. `ONLINE` or `INSTORE`
      required:
        - transactionAmount
        - orderType
    dispute:
      type: object
      properties:
        id:
          type: string
          description: Dispute identifier
        order:
          type: string
          description: The token of the order that the dispute is for.
        amount:
          type: string
          description: The amount of the dispute
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: The reason for the dispute.
        status:
          $ref: '#/components/schemas/DisputeStatus'
          description: >-
            The current state of the dispute. Values depend on how the dispute
            state machine is modeled.
        open:
          type: boolean
          default: true
          description: '`True` if a final decision on the dispute hasn''t been made yet.'
        responseDueBy:
          type: string
          description: >-
            Deadline by which the merchant must respond to the dispute. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        createdAt:
          type: string
          description: >-
            A timestamp indicating when the dispute was created. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        openingNote:
          type: string
          description: >-
            Text from the customer describing why the dispute was opened or the
            reason for the complaint. While dispute category codes are helpful
            at informing what a merchant should present, it doesn’t provide
            reasoning behind the customer’s complaint. In some cases, this can
            help merchants troubleshoot the dispute directly with their
            customers.
        openingNoteAttachments:
          type: string
          description: >-
            Attachments to supplement the `openingNote` if the customer provided
            photos or screenshots as part of their dispute description.
        updatedAt:
          type: string
          description: >-
            Timestamp when the dispute was updated. (Epoch timestamp in seconds,
            timezone UTC +0.00)
        closingReason:
          $ref: '#/components/schemas/DisputeClosingReason'
          description: >-
            A reason indicating how the final decision on the dispute was
            reached. Recommended possible values listed in Closing Reasons.
        closingNote:
          type: string
          description: >-
            Text describing in detail how the final decision on the dispute was
            reached. This supplements the `closingReason`.
        merchantOrderId:
          type: string
          description: The identifier for the transaction on the merchant side.
        transactionDate:
          type: string
          description: >-
            The timestamp of the order created by the customer. (Epoch timestamp
            in seconds, timezone UTC +0.00)
        settlementAmount:
          type: string
          description: The settlementAmount for audit usage.
        meta:
          $ref: '#/components/schemas/meta'
          description: The extra information for merchants to match payment.
      required:
        - id
        - order
        - amount
        - reason
        - status
        - open
        - responseDueBy
        - createdAt
        - openingNote
        - closingReason
        - merchantOrderId
        - transactionDate
        - settlementAmount

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Accept Dispute

GET https://global-api-sandbox.afterpay.com/v2/disputes/{dispute_id}/accept

Merchants can call this endpoint to accept a dispute case. The endpoint only works if the dispute is in a non-terminal state (the status is not `won` or `lost`).

> **Note:** Calling the API changes the dispute status to lost.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/disputes/accept-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Accept Dispute
  version: endpoint_.accept-dispute
paths:
  /v2/disputes/{dispute_id}/accept:
    get:
      operationId: accept-dispute
      summary: Accept Dispute
      description: >-
        Merchants can call this endpoint to accept a dispute case. The endpoint
        only works if the dispute is in a non-terminal state (the status is not
        `won` or `lost`).


        > **Note:** Calling the API changes the dispute status to lost.
      tags:
        - []
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - in: query
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: application/json
          required: false
          schema:
            type: string
      responses:
        '200':
          description: If successful, returns the updated dispute object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dispute'
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: product_not_received
        - value: product_unacceptable
        - value: credit_not_processed
        - value: order_canceled
        - value: duplicate
        - value: incorrect_amount
        - value: paid_by_other_means
        - value: fraudulent
        - value: fraudulent_merchant
    DisputeStatus:
      type: string
      enum:
        - value: needs_response
        - value: under_review
        - value: won
        - value: lost
        - value: merchant_refunded
        - value: merchant_voided
    DisputeClosingReason:
      type: string
      enum:
        - value: merchant_accepted
        - value: evidence_accepted
        - value: evidence_rejected
        - value: deadline_expired
        - value: customer_cancelled
    meta:
      type: object
      properties:
        transactionAmount:
          type: string
          description: The transaction amount for the order.
        network:
          type: string
          description: >-
            The payment network used by the customer. (For example, `Visa` or
            `MasterCard`)
        networkReferenceId:
          type: string
          description: The identifier for the payment.
        orderType:
          type: string
          description: The type of order. `ONLINE` or `INSTORE`
      required:
        - transactionAmount
        - orderType
    dispute:
      type: object
      properties:
        id:
          type: string
          description: Dispute identifier
        order:
          type: string
          description: The token of the order that the dispute is for.
        amount:
          type: string
          description: The amount of the dispute
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: The reason for the dispute.
        status:
          $ref: '#/components/schemas/DisputeStatus'
          description: >-
            The current state of the dispute. Values depend on how the dispute
            state machine is modeled.
        open:
          type: boolean
          default: true
          description: '`True` if a final decision on the dispute hasn''t been made yet.'
        responseDueBy:
          type: string
          description: >-
            Deadline by which the merchant must respond to the dispute. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        createdAt:
          type: string
          description: >-
            A timestamp indicating when the dispute was created. (Epoch
            timestamp in seconds, timezone UTC +0.00)
        openingNote:
          type: string
          description: >-
            Text from the customer describing why the dispute was opened or the
            reason for the complaint. While dispute category codes are helpful
            at informing what a merchant should present, it doesn’t provide
            reasoning behind the customer’s complaint. In some cases, this can
            help merchants troubleshoot the dispute directly with their
            customers.
        openingNoteAttachments:
          type: string
          description: >-
            Attachments to supplement the `openingNote` if the customer provided
            photos or screenshots as part of their dispute description.
        updatedAt:
          type: string
          description: >-
            Timestamp when the dispute was updated. (Epoch timestamp in seconds,
            timezone UTC +0.00)
        closingReason:
          $ref: '#/components/schemas/DisputeClosingReason'
          description: >-
            A reason indicating how the final decision on the dispute was
            reached. Recommended possible values listed in Closing Reasons.
        closingNote:
          type: string
          description: >-
            Text describing in detail how the final decision on the dispute was
            reached. This supplements the `closingReason`.
        merchantOrderId:
          type: string
          description: The identifier for the transaction on the merchant side.
        transactionDate:
          type: string
          description: >-
            The timestamp of the order created by the customer. (Epoch timestamp
            in seconds, timezone UTC +0.00)
        settlementAmount:
          type: string
          description: The settlementAmount for audit usage.
        meta:
          $ref: '#/components/schemas/meta'
          description: The extra information for merchants to match payment.
      required:
        - id
        - order
        - amount
        - reason
        - status
        - open
        - responseDueBy
        - createdAt
        - openingNote
        - closingReason
        - merchantOrderId
        - transactionDate
        - settlementAmount

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/dispute_id/accept")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Upload File

POST https://global-api-sandbox.afterpay.com/v2/disputes/files
Content-Type: application/json

Use this endpoint to upload files for disputes.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/disputes/upload-file

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Upload File
  version: endpoint_.upload-file
paths:
  /v2/disputes/files:
    post:
      operationId: upload-file
      summary: Upload File
      description: Use this endpoint to upload files for disputes.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: application/json
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Indicates a successful file upload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/upload-file_Response_200'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  description: The file you want to upload.
                fileType:
                  type: string
                  description: The type of file. Only `dispute_evidence` is supported.
              required:
                - file
                - fileType
components:
  schemas:
    upload-file_Response_200:
      type: object
      properties:
        id:
          type: string
          description: The ID token of the file.
        createdAt:
          type: string
          format: date-time
          description: The timestamp indicating when the file was uploaded.
        expiresAt:
          type: string
          format: date-time
          description: 'The timestamp indicating when the uploaded file expires. '

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files"

payload = {
    "file": None,
    "fileType": "string"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"file":null,"fileType":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files"

	payload := strings.NewReader("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/files")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/files', [
  'body' => '{
  "file": null,
  "fileType": "string"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "file": ,
  "fileType": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files"

payload = {
    "file": None,
    "fileType": "string"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"file":null,"fileType":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files"

	payload := strings.NewReader("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/files")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/files', [
  'body' => '{
  "file": null,
  "fileType": "string"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "file": ,
  "fileType": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files"

payload = {
    "file": None,
    "fileType": "string"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"file":null,"fileType":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files"

	payload := strings.NewReader("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/files")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/files', [
  'body' => '{
  "file": null,
  "fileType": "string"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "file": ,
  "fileType": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files"

payload = {
    "file": None,
    "fileType": "string"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"file":null,"fileType":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files"

	payload := strings.NewReader("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/disputes/files")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file\": null,\n  \"fileType\": \"string\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/disputes/files', [
  'body' => '{
  "file": null,
  "fileType": "string"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"file\": null,\n  \"fileType\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "file": ,
  "fileType": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve file

GET https://global-api-sandbox.afterpay.com/v2/disputes/files/{id}

Use this endpoint to retrieve files for disputes.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/disputes/retrieve-file

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve file
  version: endpoint_.retrieve-file
paths:
  /v2/disputes/files/{id}:
    get:
      operationId: retrieve-file
      summary: Retrieve file
      description: Use this endpoint to retrieve files for disputes.
      tags:
        - []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: query
          description: ID of the file to be retrieved.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: application/json
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Indicates that the file has been retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrieve-file_Response_200'
        '401':
          description: Unauthorized. Invalid merchant credentials.
          content: {}
        '404':
          description: Not Found. The corresponding entity can't be found for the merchant.
          content: {}
        '412':
          description: >-
            Precondition Failed. Invalid action for the dispute case, or the
            refund amount is larger than the refundable amount.
          content: {}
        '413':
          description: >-
            Request Entity Too Large. The uploaded file is too large. It must be
            less than 10 MB.
          content: {}
        '415':
          description: >-
            Unsupported Media Type. Cash App Afterpay does not support the
            filetype of the uploaded file. It must be: GIF, PDF, JPEG, or PNG.
          content: {}
        '422':
          description: Unprocessable Entity. Invalid parameter in the Dispute API request.
          content: {}
        '429':
          description: >-
            Too Many Requests. Too many requests in a short period of time,
            retry later.
          content: {}
components:
  schemas:
    retrieve-file_Response_200:
      type: object
      properties:
        url:
          type: string
          description: The link of the file to be retrieved.
        expiresAt:
          type: string
          format: date-time
          description: The timestamp indicating the expiration of the link.

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files/id"

querystring = {"id":"id"}

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files/id"

querystring = {"id":"id"}

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files/id"

querystring = {"id":"id"}

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/disputes/files/id"

querystring = {"id":"id"}

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/disputes/files/id?id=id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# dispute

<EndpointSchemaSnippet endpoint="GET /dispute-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "dp_N64jYg4RC4ZBUsXjLzE3W5",
    "order": "123456789",
    "amount": "48.46",
    "reason": "product_not_received",
    "status": "needs_response",
    "open": true,
    "responseDueBy": "1691884800",
    "createdAt": "1691880800",
    "openingNote": "Customer has no knowledge of the payment",
    "openingNoteAttachments": "[“fi_48vmw3sXdVqvtJGXbgKbAZ”]",
    "updatedAt": "1691884000",
    "closingReason": "merchant_accepted",
    "closingNote": "Merchant accepted the dispute",
    "merchantOrderId": "order54321",
    "transactionDate": "1691882800",
    "settlementAmount": "48.46",
    "meta": {
      "transactionAmount": "48.46",
      "network": "Visa",
      "networkReferenceId": "string",
      "orderType": "ONLINE"
    }
  }
  ```
</Aside>

---

# meta

<EndpointSchemaSnippet endpoint="GET /meta-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "transactionAmount": "48.46",
    "network": "Visa",
    "networkReferenceId": "string",
    "orderType": "ONLINE"
  }
  ```
</Aside>

---

# evidence

<EndpointSchemaSnippet endpoint="GET /evidence-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "productDescription": "string",
    "refundPolicy": "string",
    "refundPolicyDisclosure": "string",
    "refundRefusalExplanation": "string",
    "shippingDocumentation": "string",
    "shippingAddress": "string",
    "shippingDate": "string",
    "shippingCarrier": "string",
    "shippingTrackingNumber": "string",
    "uncategorizedFile": "string",
    "uncategorizedText": "string"
  }
  ```
</Aside>

---

# Create Grant Approval

POST https://global-api-sandbox.afterpay.com/v2/grants/approvals
Content-Type: application/json

Initiates the approval process for a new grant.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/start-grant-approval

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Grant Approval
  version: endpoint_.start-grant-approval
paths:
  /v2/grants/approvals:
    post:
      operationId: start-grant-approval
      summary: Create Grant Approval
      description: |
        Initiates the approval process for a new grant.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantApprovalResponse'
        '401':
          description: >
            Authentication failed or insufficient permissions.


            | errorCode | Description |

            | --- | --- |

            | unauthorized | The API credentials are invalid or missing. |

            | insufficient_permissions | The merchant lacks the required
            'merchant_api_v2/initiate' permission. |
          content: {}
        '403':
          description: >
            | errorCode | Description |

            | --- | --- |

            | feature_not_enabled | On file payments are not enabled for this
            merchant. |
          content: {}
        '415':
          description: Unsupported Media Type - Content-Type header is missing or invalid
          content: {}
        '422':
          description: >
            | errorCode | Description |

            | --- | --- |

            | invalid_object | One or more required fields in the request body
            were missing or invalid. |
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantApprovalRequest'
components:
  schemas:
    GrantApprovalTypeType:
      type: string
      enum:
        - value: ON_FILE
    GrantApprovalType:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/GrantApprovalTypeType'
          description: Grant Type for approval.
        merchantReference:
          type:
            - string
            - 'null'
          description: A merchant-provided reference for the grant.
      required:
        - type
    GrantApprovalRequestMerchant:
      type: object
      properties:
        redirectConfirmUrl:
          type: string
        redirectCancelUrl:
          type: string
        popupOriginUrl:
          type: string
          description: This property is optional when a `redirectConfirmURL` is provided.
        name:
          type: string
          description: The merchant name displayed in the Afterpay approval flow.
      required:
        - redirectConfirmUrl
        - redirectCancelUrl
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    GrantApprovalRequest:
      type: object
      properties:
        grants:
          type: array
          items:
            $ref: '#/components/schemas/GrantApprovalType'
          description: Grant type for approval (only single grant is supported)
        merchant:
          $ref: '#/components/schemas/GrantApprovalRequestMerchant'
        consumer:
          $ref: '#/components/schemas/Consumer'
          description: Consumer details for the grant
      required:
        - grants
        - merchant
    GrantApprovalResponse:
      type: object
      properties:
        token:
          type: string
          description: Token identifying this grant approval request
        expires:
          type: string
          format: date-time
          description: When this approval request expires
        redirectCheckoutUrl:
          type: string
          format: uri
          description: URL where the consumer should be redirected to complete approval
      required:
        - token
        - expires
        - redirectCheckoutUrl

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/approvals"

payload = {
    "grants": [{ "type": "ON_FILE" }],
    "merchant": {
        "redirectConfirmUrl": "https://example.com/approval/confirm",
        "redirectCancelUrl": "https://example.com/approval/cancel"
    }
}
headers = {
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/approvals';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"grants":[{"type":"ON_FILE"}],"merchant":{"redirectConfirmUrl":"https://example.com/approval/confirm","redirectCancelUrl":"https://example.com/approval/cancel"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/approvals"

	payload := strings.NewReader("{\n  \"grants\": [\n    {\n      \"type\": \"ON_FILE\"\n    }\n  ],\n  \"merchant\": {\n    \"redirectConfirmUrl\": \"https://example.com/approval/confirm\",\n    \"redirectCancelUrl\": \"https://example.com/approval/cancel\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/approvals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"grants\": [\n    {\n      \"type\": \"ON_FILE\"\n    }\n  ],\n  \"merchant\": {\n    \"redirectConfirmUrl\": \"https://example.com/approval/confirm\",\n    \"redirectCancelUrl\": \"https://example.com/approval/cancel\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/approvals")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"grants\": [\n    {\n      \"type\": \"ON_FILE\"\n    }\n  ],\n  \"merchant\": {\n    \"redirectConfirmUrl\": \"https://example.com/approval/confirm\",\n    \"redirectCancelUrl\": \"https://example.com/approval/cancel\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/approvals', [
  'body' => '{
  "grants": [
    {
      "type": "ON_FILE"
    }
  ],
  "merchant": {
    "redirectConfirmUrl": "https://example.com/approval/confirm",
    "redirectCancelUrl": "https://example.com/approval/cancel"
  }
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/approvals");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"grants\": [\n    {\n      \"type\": \"ON_FILE\"\n    }\n  ],\n  \"merchant\": {\n    \"redirectConfirmUrl\": \"https://example.com/approval/confirm\",\n    \"redirectCancelUrl\": \"https://example.com/approval/cancel\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "grants": [["type": "ON_FILE"]],
  "merchant": [
    "redirectConfirmUrl": "https://example.com/approval/confirm",
    "redirectCancelUrl": "https://example.com/approval/cancel"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/approvals")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create Grant

POST https://global-api-sandbox.afterpay.com/v2/grants
Content-Type: application/json

Creates a new grant from a grant approval token. 


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/create-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Grant
  version: endpoint_.create-grant
paths:
  /v2/grants:
    post:
      operationId: create-grant
      summary: Create Grant
      description: |
        Creates a new grant from a grant approval token. 
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantResponse'
        '403':
          description: >
            | errorCode | Description |

            | --- | --- |

            | feature_not_enabled | On file payments are not enabled for this
            merchant. |
          content: {}
        '412':
          description: |
            | errorCode | Description |
            | --- | --- |
            | consumer_ineligible | Consumer not eligible |
          content: {}
        '415':
          description: Unsupported Media Type - Content-Type header is missing or invalid
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGrantRequest'
components:
  schemas:
    CreateGrantRequest:
      type: object
      properties:
        requestId:
          type: string
          description: >-
            A unique request ID, required for idempotent retries. It is
            recommended that the merchant generate a UUID for each unique
            request.
        token:
          type: string
          description: The token returned from the create approval request.
        code:
          type: string
          description: |-
            The one-time code received from the consumer.
            Note: The code will only be sent with the headless integration.
      required:
        - requestId
        - token
    GrantType:
      type: string
      enum:
        - value: ON_FILE
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CANCELLED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: Unique id identifying the grant
        type:
          $ref: '#/components/schemas/GrantType'
          description: Type of grant
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: Current status of the grant
        created:
          type: string
          format: date-time
          description: Timestamp when the grant was created
        merchantReference:
          type:
            - string
            - 'null'
          description: Merchant's reference for this grant
        cancelled:
          type: string
          format: date-time
          description: If present, indicates when the grant was cancelled
        expires:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments
        consumerReference:
          type:
            - string
            - 'null'
          description: Reference identifier for the consumer
        email:
          type:
            - string
            - 'null'
          description: Masked email address of the consumer
        requestId:
          type:
            - string
            - 'null'
          description: If present, unique identifier for the request
      required:
        - id
        - type
        - status
        - created
    GrantResponse:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants"

payload = {
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"
}
headers = {
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"requestId":"123e4567-e89b-12d3-a456-426614174000","token":"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants"

	payload := strings.NewReader("{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants', [
  'body' => '{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve Grant

GET https://global-api-sandbox.afterpay.com/v2/grants/{grantId}

Retrieves a grant by its ID.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/get-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve Grant
  version: endpoint_.get-grant
paths:
  /v2/grants/{grantId}:
    get:
      operationId: get-grant
      summary: Retrieve Grant
      description: |
        Retrieves a grant by its ID.
      tags:
        - []
      parameters:
        - name: grantId
          in: path
          description: ID of the grant to retrieve.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantResponse'
        '403':
          description: >
            | errorCode | Description |

            | --- | --- |

            | feature_not_enabled | On file payments are not enabled for this
            merchant. |
          content: {}
        '404':
          description: |
            | errorCode | Description |
            | --- | --- |
            | grant_not_found | The specified grant id was not found. |
          content: {}
components:
  schemas:
    GrantType:
      type: string
      enum:
        - value: ON_FILE
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CANCELLED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: Unique id identifying the grant
        type:
          $ref: '#/components/schemas/GrantType'
          description: Type of grant
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: Current status of the grant
        created:
          type: string
          format: date-time
          description: Timestamp when the grant was created
        merchantReference:
          type:
            - string
            - 'null'
          description: Merchant's reference for this grant
        cancelled:
          type: string
          format: date-time
          description: If present, indicates when the grant was cancelled
        expires:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments
        consumerReference:
          type:
            - string
            - 'null'
          description: Reference identifier for the consumer
        email:
          type:
            - string
            - 'null'
          description: Masked email address of the consumer
        requestId:
          type:
            - string
            - 'null'
          description: If present, unique identifier for the request
      required:
        - id
        - type
        - status
        - created
    GrantResponse:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/grantId"

headers = {"Authorization": "Basic <username>:<password>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/grantId';
const options = {method: 'GET', headers: {Authorization: 'Basic <username>:<password>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/grantId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/grantId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/grants/grantId")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/grants/grantId', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/grantId");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Basic <username>:<password>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/grantId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Revoke Grant

POST https://global-api-sandbox.afterpay.com/v2/grants/{grantId}/revoke

Revokes a grant, rendering it unusable. Other endpoints will no longer be able to use the grant to perform its associated action.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/revoke-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Revoke Grant
  version: endpoint_.revoke-grant
paths:
  /v2/grants/{grantId}/revoke:
    post:
      operationId: revoke-grant
      summary: Revoke Grant
      description: >
        Revokes a grant, rendering it unusable. Other endpoints will no longer
        be able to use the grant to perform its associated action.
      tags:
        - []
      parameters:
        - name: grantId
          in: path
          description: The unique identifier id of the grant to revoke
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantResponse'
        '403':
          description: >
            | errorCode | Description |

            | --- | --- |

            | feature_not_enabled | On file payments are not enabled for this
            merchant. |
          content: {}
        '404':
          description: |
            | errorCode | Description |
            | --- | --- |
            | grant_not_found | The specified grant was not found. |
          content: {}
components:
  schemas:
    GrantType:
      type: string
      enum:
        - value: ON_FILE
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CANCELLED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: Unique id identifying the grant
        type:
          $ref: '#/components/schemas/GrantType'
          description: Type of grant
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: Current status of the grant
        created:
          type: string
          format: date-time
          description: Timestamp when the grant was created
        merchantReference:
          type:
            - string
            - 'null'
          description: Merchant's reference for this grant
        cancelled:
          type: string
          format: date-time
          description: If present, indicates when the grant was cancelled
        expires:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments
        consumerReference:
          type:
            - string
            - 'null'
          description: Reference identifier for the consumer
        email:
          type:
            - string
            - 'null'
          description: Masked email address of the consumer
        requestId:
          type:
            - string
            - 'null'
          description: If present, unique identifier for the request
      required:
        - id
        - type
        - status
        - created
    GrantResponse:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke"

headers = {"Authorization": "Basic <username>:<password>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke';
const options = {method: 'POST', headers: {Authorization: 'Basic <username>:<password>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Basic <username>:<password>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/grantId/revoke")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create Grant Alias

POST https://global-api-sandbox.afterpay.com/v2/grants/alias
Content-Type: application/json

Creates an alias for an existing grant to help load the payment schedule widget.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/alias-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Grant Alias
  version: endpoint_.alias-grant
paths:
  /v2/grants/alias:
    post:
      operationId: alias-grant
      summary: Create Grant Alias
      description: >
        Creates an alias for an existing grant to help load the payment schedule
        widget.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantAliasResponse'
        '403':
          description: >
            | errorCode | Description |

            | --- | --- |

            | feature_not_enabled | On file payments are not enabled for this
            merchant. |
          content: {}
        '415':
          description: Unsupported Media Type - Content-Type header is missing or invalid
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantAliasRequest'
components:
  schemas:
    GrantAliasRequest:
      type: object
      properties:
        token:
          type: string
          description: Token of the grant to create an alias for
        duration:
          type:
            - string
            - 'null'
          format: duration
          description: Duration of the grant in ISO-8601 period format
      required:
        - token
    GrantAliasResponse:
      type: object
      properties:
        token:
          type: string
          description: Token representing the grant alias
        expiry:
          type: string
          format: date-time
          description: Timestamp when the alias token expires
      required:
        - token
        - expiry

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/alias"

payload = { "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2" }
headers = {
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/alias';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"token":"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/alias"

	payload := strings.NewReader("{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/alias")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/alias")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/alias', [
  'body' => '{
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/alias");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = ["token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/alias")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Start Grant Link Flow

POST https://global-api-sandbox.afterpay.com/v2/grants/start
Content-Type: application/json

Initiates the headless grant link flow process.


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/start-billing-agreement-link

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Start Grant Link Flow
  version: endpoint_.start-billing-agreement-link
paths:
  /v2/grants/start:
    post:
      operationId: start-billing-agreement-link
      summary: Start Grant Link Flow
      description: |
        Initiates the headless grant link flow process.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantStartResponse'
        '404':
          description: |
            | errorCode | Description |
            | --- | --- |
            | not_found | Afterpay consumer account does not exist |
          content: {}
        '412':
          description: |
            | errorCode | Description |
            | --- | --- |
            | invalid_state | Failed to send code |
          content: {}
        '429':
          description: |
            | errorCode | Description |
            | --- | --- |
            | too_many_requests | Too many requests |
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantStartRequest'
components:
  schemas:
    GrantStartRequest:
      type: object
      properties:
        alias:
          type: string
          description: Email or phone number associated with the consumer's account
        requestId:
          type: string
          description: A unique identifier for this request
      required:
        - alias
        - requestId
    GrantStartResponseDeliveryType:
      type: string
      enum:
        - value: SMS
        - value: EMAIL
    GrantStartResponse:
      type: object
      properties:
        token:
          type: string
          description: Token identifying the grant to be created
        requestId:
          type: string
          description: The unique identifier from the request
        expiresAt:
          type: string
          format: date-time
          description: When this link attempt will expire
        deliveryType:
          $ref: '#/components/schemas/GrantStartResponseDeliveryType'
          description: How the verification code was delivered to the consumer
      required:
        - token
        - requestId
        - expiresAt
        - deliveryType

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/start"

payload = {
    "alias": "my-afterpay-email@gmail.com",
    "requestId": "123e4567-e89b-12d3-a456-426614174000"
}
headers = {
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/start';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"alias":"my-afterpay-email@gmail.com","requestId":"123e4567-e89b-12d3-a456-426614174000"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/start"

	payload := strings.NewReader("{\n  \"alias\": \"my-afterpay-email@gmail.com\",\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"alias\": \"my-afterpay-email@gmail.com\",\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/start")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"alias\": \"my-afterpay-email@gmail.com\",\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/start', [
  'body' => '{
  "alias": "my-afterpay-email@gmail.com",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/start");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"alias\": \"my-afterpay-email@gmail.com\",\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "alias": "my-afterpay-email@gmail.com",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/start")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Grant status updated

POST 

Webhook notification sent when a grant's status changes

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-afterpay/grant-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: Grant status updated
  version: __package__.grantStatusUpdated
webhooks:
  grant-status-updated:
    post:
      operationId: grant-status-updated
      summary: Grant status updated
      description: Webhook notification sent when a grant's status changes
      tags:
        - ''
      parameters: []
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnFileGrantStatusUpdated'
components:
  schemas:
    OnFileGrantStatusUpdatedDataType:
      type: string
      enum:
        - value: ON_FILE_GRANT
    GrantType:
      type: string
      enum:
        - value: ON_FILE
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CANCELLED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: Unique id identifying the grant
        type:
          $ref: '#/components/schemas/GrantType'
          description: Type of grant
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: Current status of the grant
        created:
          type: string
          format: date-time
          description: Timestamp when the grant was created
        merchantReference:
          type:
            - string
            - 'null'
          description: Merchant's reference for this grant
        cancelled:
          type: string
          format: date-time
          description: If present, indicates when the grant was cancelled
        expires:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments
        consumerReference:
          type:
            - string
            - 'null'
          description: Reference identifier for the consumer
        email:
          type:
            - string
            - 'null'
          description: Masked email address of the consumer
        requestId:
          type:
            - string
            - 'null'
          description: If present, unique identifier for the request
      required:
        - id
        - type
        - status
        - created
    OnFileGrantStatusUpdatedDataObject:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
    OnFileGrantStatusUpdatedData:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/OnFileGrantStatusUpdatedDataType'
        object:
          $ref: '#/components/schemas/OnFileGrantStatusUpdatedDataObject'
      required:
        - id
        - type
        - object
    OnFileGrantStatusUpdated:
      type: object
      properties:
        type:
          type: string
        eventId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/OnFileGrantStatusUpdatedData'
      required:
        - type
        - eventId
        - createdAt
        - data

```

---

# Retrieve Grant

POST https://global-api-sandbox.afterpay.com/v2/grants/retrieve
Content-Type: application/json

Retrieves a Cash App Pay customer grant by the ID of the customer that approved it and its own ID.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/retrieve-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve Grant
  version: endpoint_.retrieve-grant
paths:
  /v2/grants/retrieve:
    post:
      operationId: retrieve-grant
      summary: Retrieve Grant
      description: >-
        Retrieves a Cash App Pay customer grant by the ID of the customer that
        approved it and its own ID.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: Accept
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/retrieve-grant_Response_200'
        '401':
          description: Unauthenticated
          content: {}
        '403':
          description: Unauthorized
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveGrantRequest'
components:
  schemas:
    RetrieveGrantRequest:
      type: object
      properties:
        customerId:
          type: string
          description: ID of the customer that approved the customer grant.
        grantId:
          type: string
          description: ID of the customer grant to retrieve.
      required:
        - customerId
        - grantId
    CashGrantIntent:
      type: string
      enum:
        - value: ON_FILE
        - value: ONE_TIME
    CashGrantType:
      type: string
      enum:
        - value: CASHAPP
    CashGrantDetailsStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: EXPIRED
        - value: CONSUMED
        - value: REVOKED
    CashGrantDetailsCashapp:
      type: object
      properties:
        customerId:
          type: string
        cashtag:
          type: string
          description: >-
            A publicly-accessible, unique identifier (username) for individuals
            and businesses using Cash App.
      required:
        - customerId
        - cashtag
    CashGrantDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CashGrantDetailsStatus'
          description: >
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        cashapp:
          $ref: '#/components/schemas/CashGrantDetailsCashapp'
        createdAt:
          type: string
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updatedAt:
          type: string
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expiresAt:
          type: string
          description: >
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - status
        - cashapp
        - createdAt
        - updatedAt
        - expiresAt
    CashGrant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this grant issued by Cash App.
        intent:
          $ref: '#/components/schemas/CashGrantIntent'
          description: Either ON_FILE or ONE_TIME
        type:
          $ref: '#/components/schemas/CashGrantType'
          description: CASHAPP for all Cash App Pay transactions
        details:
          $ref: '#/components/schemas/CashGrantDetails'
      required:
        - id
        - intent
        - type
        - details
    retrieve-grant_Response_200:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/CashGrant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/retrieve"

payload = {
    "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/retrieve';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"customerId":"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY","grantId":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/retrieve"

	payload := strings.NewReader("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/retrieve")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/retrieve")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/retrieve', [
  'body' => '{
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/retrieve");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/retrieve")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Revoke Grant

POST https://global-api-sandbox.afterpay.com/v2/grants/revoke
Content-Type: application/json

Revokes a Cash App Pay customer grant by the ID of the customer that approved it and its own ID.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/revoke-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Revoke Grant
  version: endpoint_.revoke-grant
paths:
  /v2/grants/revoke:
    post:
      operationId: revoke-grant
      summary: Revoke Grant
      description: >-
        Revokes a Cash App Pay customer grant by the ID of the customer that
        approved it and its own ID.
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: Accept
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/revoke-grant_Response_200'
        '401':
          description: Unauthenticated
          content: {}
        '403':
          description: Unauthorized
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveGrantRequest'
components:
  schemas:
    RetrieveGrantRequest:
      type: object
      properties:
        customerId:
          type: string
          description: ID of the customer that approved the customer grant.
        grantId:
          type: string
          description: ID of the customer grant to retrieve.
      required:
        - customerId
        - grantId
    CashGrantIntent:
      type: string
      enum:
        - value: ON_FILE
        - value: ONE_TIME
    CashGrantType:
      type: string
      enum:
        - value: CASHAPP
    CashGrantDetailsStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: EXPIRED
        - value: CONSUMED
        - value: REVOKED
    CashGrantDetailsCashapp:
      type: object
      properties:
        customerId:
          type: string
        cashtag:
          type: string
          description: >-
            A publicly-accessible, unique identifier (username) for individuals
            and businesses using Cash App.
      required:
        - customerId
        - cashtag
    CashGrantDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CashGrantDetailsStatus'
          description: >
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        cashapp:
          $ref: '#/components/schemas/CashGrantDetailsCashapp'
        createdAt:
          type: string
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updatedAt:
          type: string
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expiresAt:
          type: string
          description: >
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - status
        - cashapp
        - createdAt
        - updatedAt
        - expiresAt
    CashGrant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this grant issued by Cash App.
        intent:
          $ref: '#/components/schemas/CashGrantIntent'
          description: Either ON_FILE or ONE_TIME
        type:
          $ref: '#/components/schemas/CashGrantType'
          description: CASHAPP for all Cash App Pay transactions
        details:
          $ref: '#/components/schemas/CashGrantDetails'
      required:
        - id
        - intent
        - type
        - details
    revoke-grant_Response_200:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/CashGrant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/grants/revoke"

payload = {
    "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/grants/revoke';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"customerId":"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY","grantId":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/grants/revoke"

	payload := strings.NewReader("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/grants/revoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/grants/revoke")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/grants/revoke', [
  'body' => '{
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/grants/revoke");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customerId\": \"CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY\",\n  \"grantId\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/grants/revoke")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# RetrieveGrantRequest

<EndpointSchemaSnippet endpoint="GET /retrieve-grant-request-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "grantId": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50"
  }
  ```
</Aside>

---

# Grant

<EndpointSchemaSnippet endpoint="GET /grant-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "intent": "ON_FILE",
    "type": "CASHAPP",
    "details": {
      "status": "ACTIVE",
      "cashapp": {
        "customerId": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
        "cashtag": "$someCashTag"
      },
      "createdAt": "2024-07-08T22:42:46.039Z",
      "updatedAt": "2024-07-08T22:42:46.039Z",
      "expiresAt": "2034-07-08T22:42:46.039Z"
    }
  }
  ```
</Aside>

---

# Event: grant.status.updated

POST 

**When is this event triggered?**

This event is triggered when a Cash App Pay grant status has been updated.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/grants-cash-app-pay/schemas/grant-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: grant.status.updated'
  version: subpackage_grants.grantStatusUpdated
webhooks:
  grant-status-updated:
    post:
      operationId: grant-status-updated
      summary: 'Event: grant.status.updated'
      description: >-
        **When is this event triggered?**


        This event is triggered when a Cash App Pay grant status has been
        updated.
      tags:
        - subpackage_grants
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `grant.status.updated` for
                    this event.
                eventId:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                grant:
                  $ref: '#/components/schemas/CashGrant'
                timestamp:
                  type: string
                  description: When the webhook event was created
              required:
                - type
                - eventId
                - grant
                - timestamp
components:
  schemas:
    CashGrantIntent:
      type: string
      enum:
        - value: ON_FILE
        - value: ONE_TIME
    CashGrantType:
      type: string
      enum:
        - value: CASHAPP
    CashGrantDetailsStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: EXPIRED
        - value: CONSUMED
        - value: REVOKED
    CashGrantDetailsCashapp:
      type: object
      properties:
        customerId:
          type: string
        cashtag:
          type: string
          description: >-
            A publicly-accessible, unique identifier (username) for individuals
            and businesses using Cash App.
      required:
        - customerId
        - cashtag
    CashGrantDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CashGrantDetailsStatus'
          description: >
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        cashapp:
          $ref: '#/components/schemas/CashGrantDetailsCashapp'
        createdAt:
          type: string
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updatedAt:
          type: string
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expiresAt:
          type: string
          description: >
            If present, indicates when the grant's status will become EXPIRED,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - status
        - cashapp
        - createdAt
        - updatedAt
        - expiresAt
    CashGrant:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this grant issued by Cash App.
        intent:
          $ref: '#/components/schemas/CashGrantIntent'
          description: Either ON_FILE or ONE_TIME
        type:
          $ref: '#/components/schemas/CashGrantType'
          description: CASHAPP for all Cash App Pay transactions
        details:
          $ref: '#/components/schemas/CashGrantDetails'
      required:
        - id
        - intent
        - type
        - details

```

---

# Create Order

POST https://global-api-sandbox.afterpay.com/v2/orders
Content-Type: application/json

This is the first step in the on file grant purchase process. Use the token in the response to initiate the payment


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/orders/create-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Order
  version: endpoint_.create-grant
paths:
  /v2/orders:
    post:
      operationId: create-grant
      summary: Create Order
      description: >
        This is the first step in the on file grant purchase process. Use the
        token in the response to initiate the payment
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '415':
          description: Unsupported Media Type
          content: {}
        '422':
          description: >
            | errorCode | Description |

            | --- | --- |

            | invalid_object             | One or more required fields were
            missing or invalid.                     |

            | unsupported_payment_type   | The amount is outside of the
            merchant's payment limits, as returned by Get Configuration. |

            | unsupported_currency       | The amount is outside of the
            merchant's payment limits, as returned by Get Configuration. |
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    InitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    Initiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/InitiationActor'
          description: The party who initiated the order
      required:
        - actor
    SubscriptionType:
      type: string
      enum:
        - value: FIXED
        - value: VARIABLE
    SubscriptionInterval:
      type: string
      enum:
        - value: DAY
        - value: WEEK
        - value: MONTH
        - value: YEAR
    Subscription:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionType'
        interval:
          $ref: '#/components/schemas/SubscriptionInterval'
        intervalCount:
          type: integer
    Enrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/Initiation'
          description: Who initiated the order
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: Metadata on the subscription details
      required:
        - initiation
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    OrderRequest:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: A unique identifier for the request, used for idempotency
        grantId:
          type: string
          description: ID of the grant used to create this order
        amount:
          $ref: '#/components/schemas/Money'
          description: The total amount of the order
        enrichments:
          $ref: '#/components/schemas/Enrichments'
          description: Describes additional fields beyond core payment information.
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        shipping:
          $ref: '#/components/schemas/Contact'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        merchantReference:
          type: string
          description: The reference/order ID in the merchant's system
        shippingAmount:
          $ref: '#/components/schemas/Money'
          description: The shipping cost amount
        taxAmount:
          $ref: '#/components/schemas/Money'
          description: The tax amount
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
      required:
        - requestId
        - grantId
        - amount
        - enrichments
    CreateOrderResponse:
      type: object
      properties:
        token:
          type: string
        expires:
          type: string
          format: date-time
      required:
        - token
        - expires

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/orders"

payload = {
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "grantId": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
    "amount": {
        "amount": "100.00",
        "currency": "AUD"
    },
    "enrichments": { "initiation": { "actor": "CUSTOMER" } }
}
headers = {
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/orders';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"requestId":"123e4567-e89b-12d3-a456-426614174000","grantId":"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2","amount":{"amount":"100.00","currency":"AUD"},"enrichments":{"initiation":{"actor":"CUSTOMER"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/orders"

	payload := strings.NewReader("{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"grantId\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"CUSTOMER\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"grantId\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"CUSTOMER\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/orders")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"grantId\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"CUSTOMER\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/orders', [
  'body' => '{
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "grantId": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
  "amount": {
    "amount": "100.00",
    "currency": "AUD"
  },
  "enrichments": {
    "initiation": {
      "actor": "CUSTOMER"
    }
  }
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/orders");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requestId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"grantId\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"CUSTOMER\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "grantId": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
  "amount": [
    "amount": "100.00",
    "currency": "AUD"
  ],
  "enrichments": ["initiation": ["actor": "CUSTOMER"]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/orders")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# List Payments

GET https://global-api-sandbox.afterpay.com/v2/payments

This endpoint retrieves a collection of payments along with their order details.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 20             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/list-payments

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List Payments
  version: endpoint_.list-payments
paths:
  /v2/payments:
    get:
      operationId: list-payments
      summary: List Payments
      description: >
        This endpoint retrieves a collection of payments along with their order
        details.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 20             |
      tags:
        - []
      parameters:
        - name: toCreatedDate
          in: query
          description: >-
            An inclusive end date and time to search, in [ISO
            8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
          required: false
          schema:
            type: string
            default: '2020-12-30'
        - name: fromCreatedDate
          in: query
          description: >-
            An inclusive start date and time to search, in [ISO
            8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
          required: false
          schema:
            type: string
            default: '2020-01-01'
        - name: tokens
          in: query
          description: One or more order tokens to search for.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: includeNextLink
          in: query
          description: >-
            Returns a modified pagination object which includes a URL to return
            the next page. The default value is false.
          required: false
          schema:
            type: boolean
            default: false
        - name: ids
          in: query
          description: One or more Cash App Afterpay Order IDs to search for.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: merchantReferences
          in: query
          description: One or more Merchant Reference IDs to search for.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: statuses
          in: query
          description: >-
            One or more Cash App Afterpay Order Statuses to search for. Possible
            values include "APPROVED" and "DECLINED".
          required: false
          schema:
            type: array
            items:
              type: string
        - name: orderBy
          in: query
          description: >-
            A field to order results by. If provided, must be one of
            "createdAt", "id", "totalAmount", "merchantReference" or "email".
          required: false
          schema:
            type: string
            default: createdAt
        - name: ascending
          in: query
          description: >-
            `true` to order results in ascending order, or `false` for
            descending order.
          required: false
          schema:
            type: boolean
            default: false
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: >-
            Returns the matching Payment objects, enclosed in a Pagination
            object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-payments_Response_200'
        '422':
          description: >-
            An invalid query parameter was provided. For example, a value for
            `limit` was provided, but was less than 1 or more than 250. Error
            code `error`.
          content: {}
        '500':
          description: >-
            This is usually caused by sending a `fromCreatedDate` or
            `toCreatedDate` in an invalid format. Please ensure the dash and
            colon characters are included, and any plus characters are
            URL-encoded. Also, for the array parameters (`ids`, `tokens`,
            `merchantReferences` and `statuses`), do not use comma-separated
            values or square brackets. Instead, include each parameter multiple
            times, as needed.
          content: {}
components:
  schemas:
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'
    list-payments_Response_200:
      type: object
      properties:
        totalResults:
          type: integer
          description: Total number of results
        offset:
          type: integer
          description: The offer of the pagination
        limit:
          type: integer
          description: The number of payments to include in the results
        results:
          type: array
          items:
            $ref: '#/components/schemas/Payment'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/payments")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/payments', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Auth

POST https://global-api-sandbox.afterpay.com/v2/payments/auth
Content-Type: application/json

This endpoint requests a payment auth, which determines the order approval status. If approved, the auth has an expiration date and time, which is returned in the events list for the "AUTH_APPROVED" payment event. Authorization expires after 13 days.

This operation is idempotent based on the `requestId` (if provided), which allows for the safe retry of multiple requests, guaranteeing the payment operation is only made once.

The customer's payment plan starts at the time of auth approval.

**Note:** Authorization expires after 13 days and then the transaction is automatically voided. Voided transactions are frozen and cannot be reopened or changed in any way. In this case, use the `v2/checkouts` endpoint to create a new order.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 70             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/auth

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Auth
  version: endpoint_.auth
paths:
  /v2/payments/auth:
    post:
      operationId: auth
      summary: Auth
      description: >
        This endpoint requests a payment auth, which determines the order
        approval status. If approved, the auth has an expiration date and time,
        which is returned in the events list for the "AUTH_APPROVED" payment
        event. Authorization expires after 13 days.


        This operation is idempotent based on the `requestId` (if provided),
        which allows for the safe retry of multiple requests, guaranteeing the
        payment operation is only made once.


        The customer's payment plan starts at the time of auth approval.


        **Note:** Authorization expires after 13 days and then the transaction
        is automatically voided. Voided transactions are frozen and cannot be
        reopened or changed in any way. In this case, use the `v2/checkouts`
        endpoint to create a new order.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 70             |
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: >-
            If the payment is approved by Cash App Afterpay, a Payment object is
            returned with a `status` of **APPROVED** and a `paymentState` of
            **AUTH_APPROVED**.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAuth'
        '402':
          description: >
            If payment is declined by Cash App Afterpay, for example, if invalid
            card details were entered, returns a Payment object in response,
            with a `status` of "DECLINED" and a `paymentState` of
            "AUTH_DECLINED". advise the customer to contact the Cash App
            Afterpay Customer Service team for more information.


            As well, the following errorCodes are possible:

            | errorCode | Description |

            | --- | --- |

            | invalid_token | The checkout token is invalid, expired, or does
            not exist.
          content: {}
        '412':
          description: >-
            The customer has not confirmed their payment for the order
            associated with this token. Error code
            `invalid_order_transaction_status`.
          content: {}
        '422':
          description: >-
            The checkout token was missing or empty. Error code
            `invalid_object`.
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizePayment'
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    InitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    Initiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/InitiationActor'
          description: The party who initiated the order
      required:
        - actor
    SubscriptionType:
      type: string
      enum:
        - value: FIXED
        - value: VARIABLE
    SubscriptionInterval:
      type: string
      enum:
        - value: DAY
        - value: WEEK
        - value: MONTH
        - value: YEAR
    Subscription:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionType'
        interval:
          $ref: '#/components/schemas/SubscriptionInterval'
        intervalCount:
          type: integer
    Enrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/Initiation'
          description: Who initiated the order
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: Metadata on the subscription details
      required:
        - initiation
    AuthorizePayment:
      type: object
      properties:
        requestid:
          type: string
          format: uuid
          description: >-
            A unique request ID, required for idempotent retries. We recommend
            that merchants generate a Universally Unique Identifier (UUID) for
            each unique request.
        token:
          type: string
        merchantReference:
          type: string
          description: >-
            The reference/order ID that this payment corresponds to in the
            merchant's system.


            **Note:** Providing a new value updates any value previously set in
            the Create Checkout request.
        amount:
          $ref: '#/components/schemas/Money'
          description: >-
            **Required for express checkout only.** Amount to be checked against
            the value in the create checkout request. If the amounts do not
            match, then the request is rejected and an error specific to this
            scenario is returned.
        isCheckoutAdjusted:
          type: boolean
          description: >-
            **Express checkout only.** The isCheckoutAdjusted field can be used
            to allow the order amount to be changed after the checkout flow.
            Used for express checkout.
        paymentScheduleChecksum:
          type: string
          description: >-
            **Express checkout only.** A unique value representing the payment
            schedule that must be provided when there has been changes since the
            initial order creation (retrieved from checkout widget).
        items:
          type: array
          items:
            description: Any type
          description: >-
            **Express checkout only.** An array of order items that have been
            updated to be provided if it has changed since the initial order
            creation.
        shipping:
          $ref: '#/components/schemas/Contact'
          description: >-
            **Express checkout only.** The shipping address if it has changed
            since the initial order creation.
        enrichments:
          $ref: '#/components/schemas/Enrichments'
      required:
        - token
    PaymentAuthStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    PaymentAuthPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    PaymentAuth:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentAuthStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentAuthPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/auth"

payload = {
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
    "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
    "merchantReference": "merchant-order-123",
    "amount": {
        "amount": "100.00",
        "currency": "AUD"
    },
    "isCheckoutAdjusted": True,
    "paymentScheduleChecksum": "string",
    "items": [None],
    "shipping": {
        "name": "Joe Consumer",
        "line1": "Level 5",
        "area1": "Melbourne",
        "region": "VIC",
        "postcode": "3000",
        "countryCode": "AU",
        "line2": "390 Collins Street",
        "phoneNumber": "0400 000 000"
    },
    "enrichments": { "initiation": { "actor": "MERCHANT" } }
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/auth';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"token":"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2","requestid":"d22f5305-05f3-48a0-9131-a4e6e5f58b9a","merchantReference":"merchant-order-123","amount":{"amount":"100.00","currency":"AUD"},"isCheckoutAdjusted":true,"paymentScheduleChecksum":"string","items":[null],"shipping":{"name":"Joe Consumer","line1":"Level 5","area1":"Melbourne","region":"VIC","postcode":"3000","countryCode":"AU","line2":"390 Collins Street","phoneNumber":"0400 000 000"},"enrichments":{"initiation":{"actor":"MERCHANT"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/auth"

	payload := strings.NewReader("{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": [\n    null\n  ],\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"MERCHANT\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/auth")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": [\n    null\n  ],\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"MERCHANT\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/auth")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": [\n    null\n  ],\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"MERCHANT\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/auth', [
  'body' => '{
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "merchantReference": "merchant-order-123",
  "amount": {
    "amount": "100.00",
    "currency": "AUD"
  },
  "isCheckoutAdjusted": true,
  "paymentScheduleChecksum": "string",
  "items": [
    null
  ],
  "shipping": {
    "name": "Joe Consumer",
    "line1": "Level 5",
    "area1": "Melbourne",
    "region": "VIC",
    "postcode": "3000",
    "countryCode": "AU",
    "line2": "390 Collins Street",
    "phoneNumber": "0400 000 000"
  },
  "enrichments": {
    "initiation": {
      "actor": "MERCHANT"
    }
  }
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/auth");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": [\n    null\n  ],\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  },\n  \"enrichments\": {\n    \"initiation\": {\n      \"actor\": \"MERCHANT\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "merchantReference": "merchant-order-123",
  "amount": [
    "amount": "100.00",
    "currency": "AUD"
  ],
  "isCheckoutAdjusted": true,
  "paymentScheduleChecksum": "string",
  "items": [],
  "shipping": [
    "name": "Joe Consumer",
    "line1": "Level 5",
    "area1": "Melbourne",
    "region": "VIC",
    "postcode": "3000",
    "countryCode": "AU",
    "line2": "390 Collins Street",
    "phoneNumber": "0400 000 000"
  ],
  "enrichments": ["initiation": ["actor": "MERCHANT"]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/auth")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/auth"

payload = {
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
    "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
    "merchantReference": "merchant-order-123"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/auth';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"token":"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2","requestid":"d22f5305-05f3-48a0-9131-a4e6e5f58b9a","merchantReference":"merchant-order-123"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/auth"

	payload := strings.NewReader("{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/auth")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/auth")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/auth', [
  'body' => '{
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "merchantReference": "merchant-order-123"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/auth");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"token\": \"005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2\",\n  \"requestid\": \"d22f5305-05f3-48a0-9131-a4e6e5f58b9a\",\n  \"merchantReference\": \"merchant-order-123\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
  "merchantReference": "merchant-order-123"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/auth")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Capture Full Payment

POST https://global-api-sandbox.afterpay.com/v2/payments/capture
Content-Type: application/json

This endpoint makes a payment capture for the full value of the payment plan.

This operation is idempotent based on the token, which allows for the safe retry of requests, guaranteeing the payment operation is only made once.

Since the idempotency of this endpoint is based on the token, the inclusion of a `requestId` is not required.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 70             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/capture-full-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Capture Full Payment
  version: endpoint_.capture-full-payment
paths:
  /v2/payments/capture:
    post:
      operationId: capture-full-payment
      summary: Capture Full Payment
      description: >
        This endpoint makes a payment capture for the full value of the payment
        plan.


        This operation is idempotent based on the token, which allows for the
        safe retry of requests, guaranteeing the payment operation is only made
        once.


        Since the idempotency of this endpoint is based on the token, the
        inclusion of a `requestId` is not required.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 70             |
      tags:
        - []
      parameters:
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: >
            | Status | Description |

            | ----- | ----- |

            | `APPROVED` | If payment is approved by Cash App Afterpay, returns
            a Payment object in response, with a status of "APPROVED". |

            | `DECLINED` | If payment is declined by Cash App Afterpay, for
            example, if invalid card details were entered, returns a Payment
            object in response, with a status of "DECLINED". Please advise the
            customer to contact the Cash App Afterpay Customer Service team for
            more information. |
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '402':
          description: >-
            The checkout token is invalid, expired, or does not exist. Error
            code `invalid_token`.
          content: {}
        '412':
          description: >-
            The Consumer has not confirmed their payment for the order
            associated with this token. Error code
            `invalid_order_transaction_status`.
          content: {}
        '422':
          description: >-
            The checkout token was missing or empty. Error code
            `invalid_object`.
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The token returned in the Create Checkout request.
                merchantReference:
                  type: string
                  description: >-
                    The merchant’s order id/reference that this payment
                    corresponds to. This updates any value previously provided
                    in the Create Checkout request.
                amount:
                  $ref: '#/components/schemas/Money'
                  description: >-
                    **Required for express checkout only.** Amount to be checked
                    against the value in the create checkout request. If the
                    amounts do not match, then the request is rejected and an
                    error specific to this scenario is returned. 
                isCheckoutAdjusted:
                  type: boolean
                  description: >-
                    **Express checkout only.** The isCheckoutAdjusted field can
                    be used to allow the order amount to be changed after the
                    checkout flow.
                paymentScheduleChecksum:
                  type: string
                  description: >-
                    **Express checkout only.** A unique value representing the
                    payment schedule that must be provided when there have been
                    changes since the initial order creation (retrieved from
                    checkout widget).
                items:
                  $ref: '#/components/schemas/Item'
                  description: >-
                    **Express checkout only.** An array of order items that have
                    been updated. Provide if it has changed since the initial
                    order creation.
                shipping:
                  $ref: '#/components/schemas/Contact'
                  description: >-
                    **Express checkout only.** The shipping address if it has
                    changed since the initial order creation. 
                enrichments:
                  $ref: '#/components/schemas/Enrichments'
              required:
                - token
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    InitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    Initiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/InitiationActor'
          description: The party who initiated the order
      required:
        - actor
    SubscriptionType:
      type: string
      enum:
        - value: FIXED
        - value: VARIABLE
    SubscriptionInterval:
      type: string
      enum:
        - value: DAY
        - value: WEEK
        - value: MONTH
        - value: YEAR
    Subscription:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionType'
        interval:
          $ref: '#/components/schemas/SubscriptionInterval'
        intervalCount:
          type: integer
    Enrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/Initiation'
          description: Who initiated the order
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: Metadata on the subscription details
      required:
        - initiation
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/capture"

payload = {
    "token": "string",
    "merchantReference": "string",
    "amount": {
        "amount": "100.00",
        "currency": "AUD"
    },
    "isCheckoutAdjusted": True,
    "paymentScheduleChecksum": "string",
    "items": {
        "name": "Blue Carabiner",
        "quantity": 1,
        "price": {
            "amount": "40.00",
            "currency": "AUD"
        },
        "sku": "12341234",
        "pageUrl": "https://merchant.example.com/carabiner-354193.html",
        "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
        "categories": [["Sporting Goods", "Climbing Equipment", "Climbing", "Climbing Carabiners"], ["Sale", "Climbing"]],
        "estimatedShipmentDate": "2023-08-01"
    },
    "shipping": {
        "name": "Joe Consumer",
        "line1": "Level 5",
        "area1": "Melbourne",
        "region": "VIC",
        "postcode": "3000",
        "countryCode": "AU",
        "line2": "390 Collins Street",
        "phoneNumber": "0400 000 000"
    }
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/capture';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"token":"string","merchantReference":"string","amount":{"amount":"100.00","currency":"AUD"},"isCheckoutAdjusted":true,"paymentScheduleChecksum":"string","items":{"name":"Blue Carabiner","quantity":1,"price":{"amount":"40.00","currency":"AUD"},"sku":"12341234","pageUrl":"https://merchant.example.com/carabiner-354193.html","imageUrl":"https://merchant.example.com/carabiner-7378-391453-1.jpg","categories":[["Sporting Goods","Climbing Equipment","Climbing","Climbing Carabiners"],["Sale","Climbing"]],"estimatedShipmentDate":"2023-08-01"},"shipping":{"name":"Joe Consumer","line1":"Level 5","area1":"Melbourne","region":"VIC","postcode":"3000","countryCode":"AU","line2":"390 Collins Street","phoneNumber":"0400 000 000"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/capture"

	payload := strings.NewReader("{\n  \"token\": \"string\",\n  \"merchantReference\": \"string\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": {\n    \"name\": \"Blue Carabiner\",\n    \"quantity\": 1,\n    \"price\": {\n      \"amount\": \"40.00\",\n      \"currency\": \"AUD\"\n    },\n    \"sku\": \"12341234\",\n    \"pageUrl\": \"https://merchant.example.com/carabiner-354193.html\",\n    \"imageUrl\": \"https://merchant.example.com/carabiner-7378-391453-1.jpg\",\n    \"categories\": [\n      [\n        \"Sporting Goods\",\n        \"Climbing Equipment\",\n        \"Climbing\",\n        \"Climbing Carabiners\"\n      ],\n      [\n        \"Sale\",\n        \"Climbing\"\n      ]\n    ],\n    \"estimatedShipmentDate\": \"2023-08-01\"\n  },\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/capture")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"token\": \"string\",\n  \"merchantReference\": \"string\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": {\n    \"name\": \"Blue Carabiner\",\n    \"quantity\": 1,\n    \"price\": {\n      \"amount\": \"40.00\",\n      \"currency\": \"AUD\"\n    },\n    \"sku\": \"12341234\",\n    \"pageUrl\": \"https://merchant.example.com/carabiner-354193.html\",\n    \"imageUrl\": \"https://merchant.example.com/carabiner-7378-391453-1.jpg\",\n    \"categories\": [\n      [\n        \"Sporting Goods\",\n        \"Climbing Equipment\",\n        \"Climbing\",\n        \"Climbing Carabiners\"\n      ],\n      [\n        \"Sale\",\n        \"Climbing\"\n      ]\n    ],\n    \"estimatedShipmentDate\": \"2023-08-01\"\n  },\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/capture")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"token\": \"string\",\n  \"merchantReference\": \"string\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": {\n    \"name\": \"Blue Carabiner\",\n    \"quantity\": 1,\n    \"price\": {\n      \"amount\": \"40.00\",\n      \"currency\": \"AUD\"\n    },\n    \"sku\": \"12341234\",\n    \"pageUrl\": \"https://merchant.example.com/carabiner-354193.html\",\n    \"imageUrl\": \"https://merchant.example.com/carabiner-7378-391453-1.jpg\",\n    \"categories\": [\n      [\n        \"Sporting Goods\",\n        \"Climbing Equipment\",\n        \"Climbing\",\n        \"Climbing Carabiners\"\n      ],\n      [\n        \"Sale\",\n        \"Climbing\"\n      ]\n    ],\n    \"estimatedShipmentDate\": \"2023-08-01\"\n  },\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/capture', [
  'body' => '{
  "token": "string",
  "merchantReference": "string",
  "amount": {
    "amount": "100.00",
    "currency": "AUD"
  },
  "isCheckoutAdjusted": true,
  "paymentScheduleChecksum": "string",
  "items": {
    "name": "Blue Carabiner",
    "quantity": 1,
    "price": {
      "amount": "40.00",
      "currency": "AUD"
    },
    "sku": "12341234",
    "pageUrl": "https://merchant.example.com/carabiner-354193.html",
    "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
    "categories": [
      [
        "Sporting Goods",
        "Climbing Equipment",
        "Climbing",
        "Climbing Carabiners"
      ],
      [
        "Sale",
        "Climbing"
      ]
    ],
    "estimatedShipmentDate": "2023-08-01"
  },
  "shipping": {
    "name": "Joe Consumer",
    "line1": "Level 5",
    "area1": "Melbourne",
    "region": "VIC",
    "postcode": "3000",
    "countryCode": "AU",
    "line2": "390 Collins Street",
    "phoneNumber": "0400 000 000"
  }
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/capture");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"token\": \"string\",\n  \"merchantReference\": \"string\",\n  \"amount\": {\n    \"amount\": \"100.00\",\n    \"currency\": \"AUD\"\n  },\n  \"isCheckoutAdjusted\": true,\n  \"paymentScheduleChecksum\": \"string\",\n  \"items\": {\n    \"name\": \"Blue Carabiner\",\n    \"quantity\": 1,\n    \"price\": {\n      \"amount\": \"40.00\",\n      \"currency\": \"AUD\"\n    },\n    \"sku\": \"12341234\",\n    \"pageUrl\": \"https://merchant.example.com/carabiner-354193.html\",\n    \"imageUrl\": \"https://merchant.example.com/carabiner-7378-391453-1.jpg\",\n    \"categories\": [\n      [\n        \"Sporting Goods\",\n        \"Climbing Equipment\",\n        \"Climbing\",\n        \"Climbing Carabiners\"\n      ],\n      [\n        \"Sale\",\n        \"Climbing\"\n      ]\n    ],\n    \"estimatedShipmentDate\": \"2023-08-01\"\n  },\n  \"shipping\": {\n    \"name\": \"Joe Consumer\",\n    \"line1\": \"Level 5\",\n    \"area1\": \"Melbourne\",\n    \"region\": \"VIC\",\n    \"postcode\": \"3000\",\n    \"countryCode\": \"AU\",\n    \"line2\": \"390 Collins Street\",\n    \"phoneNumber\": \"0400 000 000\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "token": "string",
  "merchantReference": "string",
  "amount": [
    "amount": "100.00",
    "currency": "AUD"
  ],
  "isCheckoutAdjusted": true,
  "paymentScheduleChecksum": "string",
  "items": [
    "name": "Blue Carabiner",
    "quantity": 1,
    "price": [
      "amount": "40.00",
      "currency": "AUD"
    ],
    "sku": "12341234",
    "pageUrl": "https://merchant.example.com/carabiner-354193.html",
    "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
    "categories": [["Sporting Goods", "Climbing Equipment", "Climbing", "Climbing Carabiners"], ["Sale", "Climbing"]],
    "estimatedShipmentDate": "2023-08-01"
  ],
  "shipping": [
    "name": "Joe Consumer",
    "line1": "Level 5",
    "area1": "Melbourne",
    "region": "VIC",
    "postcode": "3000",
    "countryCode": "AU",
    "line2": "390 Collins Street",
    "phoneNumber": "0400 000 000"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/capture")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/capture"

payload = {
    "token": "{{afterpay_checkout_token}}",
    "merchantReference": "{{merchant_order_number}}"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/capture';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"token":"{{afterpay_checkout_token}}","merchantReference":"{{merchant_order_number}}"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/capture"

	payload := strings.NewReader("{\n  \"token\": \"{{afterpay_checkout_token}}\",\n  \"merchantReference\": \"{{merchant_order_number}}\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/capture")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"token\": \"{{afterpay_checkout_token}}\",\n  \"merchantReference\": \"{{merchant_order_number}}\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/capture")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"token\": \"{{afterpay_checkout_token}}\",\n  \"merchantReference\": \"{{merchant_order_number}}\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/capture', [
  'body' => '{
  "token": "{{afterpay_checkout_token}}",
  "merchantReference": "{{merchant_order_number}}"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/capture");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"token\": \"{{afterpay_checkout_token}}\",\n  \"merchantReference\": \"{{merchant_order_number}}\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "token": "{{afterpay_checkout_token}}",
  "merchantReference": "{{merchant_order_number}}"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/capture")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Get Payment By Order ID

GET https://global-api-sandbox.afterpay.com/v2/payments/{orderId}

This endpoint retrieves an individual payment along with its order details.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 20             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/get-payment-by-order-id

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Payment By Order ID
  version: endpoint_.get-payment-by-order-id
paths:
  /v2/payments/{orderId}:
    get:
      operationId: get-payment-by-order-id
      summary: Get Payment By Order ID
      description: >
        This endpoint retrieves an individual payment along with its order
        details.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 20             |
      tags:
        - []
      parameters:
        - name: orderId
          in: path
          description: >-
            The unique ID of the Cash App Afterpay Order, for which a Payment
            event has been completed.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: Returns a Payment object in response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          description: >-
            No Cash App Afterpay Order was found matching the `orderId`
            provided. Error code `not_found`.
          content: {}
components:
  schemas:
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/orderId"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/orderId';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/orderId"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/orderId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/payments/orderId")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/payments/orderId', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/orderId");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/orderId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Update Payment by Order ID

PUT https://global-api-sandbox.afterpay.com/v2/payments/{orderId}
Content-Type: application/json

This endpoint is to create merchant side order ID's following the Cash App Afterpay order ID creation. Call the endpoint immediately after the Cash App Afterpay order is created.

Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/update-payment-by-order-id

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Payment by Order ID
  version: endpoint_.update-payment-by-order-id
paths:
  /v2/payments/{orderId}:
    put:
      operationId: update-payment-by-order-id
      summary: Update Payment by Order ID
      description: >-
        This endpoint is to create merchant side order ID's following the Cash
        App Afterpay order ID creation. Call the endpoint immediately after the
        Cash App Afterpay order is created.
      tags:
        - []
      parameters:
        - name: orderId
          in: path
          description: The Order ID to update
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: Returns object containing the following attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-payment-by-order-id_Response_201'
        '404':
          description: >-
            The Cash App Afterpay payment ID to update was not found. Error code
            `not_found`.
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantReference:
                  type: string
                  default: new_merchant_order_id_1234
                  description: The merchant’s new order ID to replace with
              required:
                - merchantReference
components:
  schemas:
    V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaOriginalAmount:
      type: object
      properties: {}
    V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaOpenToCaptureAmount:
      type: object
      properties: {}
    V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaRefunds:
      type: object
      properties: {}
    V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaOrderDetails:
      type: object
      properties: {}
    V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaEvents:
      type: object
      properties: {}
    update-payment-by-order-id_Response_201:
      type: object
      properties:
        id:
          type: string
          description: The unique Cash App Afterpay (merchant payment) payment ID.
        token:
          type: string
          description: Checkout token to be used to complete customer checkout and payment.
        status:
          type: string
          description: \"APPROVED" (update is only valid for successful orders)
        created:
          description: >-
            The payment creation time [ISO 8601 UTC/Zulu
            time](https://www.iso.org/iso-8601-date-and-time-format.html).
        originalAmount:
          $ref: >-
            #/components/schemas/V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaOriginalAmount
          description: Total amount for the order. See Money.
        openToCaptureAmount:
          $ref: >-
            #/components/schemas/V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaOpenToCaptureAmount
          description: Total amount that can be captured for order. See Money.
        paymentState:
          type: string
          description: >-
            Available states: "AUTH_APPROVED", "CAPTURED", "VOIDED", "EXPIRED",
            "AUTH_DECLINED", "PARTIALLY_CAPTURED", "CAPTURE_DECLINED""
        merchantReference:
          description: Any type
        refunds:
          $ref: >-
            #/components/schemas/V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaRefunds
          description: The refund details for merchant's order. See Refund.
        orderDetails:
          $ref: >-
            #/components/schemas/V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaOrderDetails
          description: The order bound to the payment. See Order Details.
        events:
          $ref: >-
            #/components/schemas/V2PaymentsOrderIdPutResponsesContentApplicationJsonSchemaEvents
          description: Event list for for merchant's order. See Events.

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/orderId"

payload = { "merchantReference": "new_merchant_order_id_1234" }
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/orderId';
const options = {
  method: 'PUT',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"merchantReference":"new_merchant_order_id_1234"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/orderId"

	payload := strings.NewReader("{\n  \"merchantReference\": \"new_merchant_order_id_1234\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/orderId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantReference\": \"new_merchant_order_id_1234\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://global-api-sandbox.afterpay.com/v2/payments/orderId")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantReference\": \"new_merchant_order_id_1234\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://global-api-sandbox.afterpay.com/v2/payments/orderId', [
  'body' => '{
  "merchantReference": "new_merchant_order_id_1234"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/orderId");
var request = new RestRequest(Method.PUT);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchantReference\": \"new_merchant_order_id_1234\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = ["merchantReference": "new_merchant_order_id_1234"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/orderId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Capture Payment

POST https://global-api-sandbox.afterpay.com/v2/payments/{orderId}/capture
Content-Type: application/json

This endpoint captures a full or partial payment. Any amounts successfully captured are settled from Cash App Afterpay to the merchant's nominated bank account on the following day. Records of all payments captured against an order are returned in the events list as events of type, "CAPTURED".

**Note:** Authorization expires after 13 days and then the transaction is automatically voided. Voided transactions are frozen and cannot be captured, reopened or changed in any way. In this case your only option is to use the v2/checkouts endpoint to create a new order.

This operation is idempotent based on the `requestId` (if provided), which allows the safe retry of multiple requests. This safe retry guarantees the payment operation only occurs once.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 70             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/capture-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Capture Payment
  version: endpoint_.capture-payment
paths:
  /v2/payments/{orderId}/capture:
    post:
      operationId: capture-payment
      summary: Capture Payment
      description: >
        This endpoint captures a full or partial payment. Any amounts
        successfully captured are settled from Cash App Afterpay to the
        merchant's nominated bank account on the following day. Records of all
        payments captured against an order are returned in the events list as
        events of type, "CAPTURED".


        **Note:** Authorization expires after 13 days and then the transaction
        is automatically voided. Voided transactions are frozen and cannot be
        captured, reopened or changed in any way. In this case your only option
        is to use the v2/checkouts endpoint to create a new order.


        This operation is idempotent based on the `requestId` (if provided),
        which allows the safe retry of multiple requests. This safe retry
        guarantees the payment operation only occurs once.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 70             |
      tags:
        - []
      parameters:
        - name: orderId
          in: path
          description: >-
            The unique ID of the Cash App Afterpay Order, returned as the `id`
            property of the Auth response.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: >-
            If successful, returns an updated copy of the Payment object, with
            the newly captured payment appended to the `events` array as a
            Payment Event object with a `type` of "CAPTURED".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          description: >-
            No numeric `orderId` was provided, or an invalid string was
            provided. Error code `not_found`.
          content: {}
        '410':
          description: >-
            Payment has already been fully captured for this order, or partially
            captured with the remainder voided. Error code `payment_captured`.
          content: {}
        '412':
          description: >
            | errorCode | Description |

            | --- | --- |

            | error | A numeric `orderId` was provided, but did not match any
            valid order. |

            | invalid_state | The order was declined by Cash App Afterpay; no
            payment can be captured for this order. |

            | payment_voided | The auth for this order has already been
            completely voided. |

            | payment_expired | The auth for this order has expired; no further
            payment can be captured. |
          content: {}
        '422':
          description: >
            | errorCode | Description |

            | --- | --- |

            | invalid_object | The `amount` was missing or invalid, or the
            `paymentEventMerchantReference` exceeded 128 characters. |

            | invalid_amount | The `amount` was less than the minimum capture
            amount, or more than the `openToCaptureAmount`. |
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapturePayment'
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    CapturePayment:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: A unique request ID, required for idempotent retries.
        merchantReference:
          type: string
          description: >-
            The reference/order ID that this payment corresponds to in the
            merchant's system. 


            Note: Providing a new value updates any value previously set in the
            Create Checkout request.
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
          description: >
            A unique reference for the individual payment capture event. If
            provided, the value appears in the daily settlement file as "Payment
            Event ID"
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/orderId/capture")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Update Shipping Courier

PUT https://global-api-sandbox.afterpay.com/v2/payments/{orderId}/courier
Content-Type: application/json

This endpoint updates an order with shipping courier information. The Cash App Afterpay team may use this information when providing support.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 20             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/update-shipping-courier

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update Shipping Courier
  version: endpoint_.update-shipping-courier
paths:
  /v2/payments/{orderId}/courier:
    put:
      operationId: update-shipping-courier
      summary: Update Shipping Courier
      description: >
        This endpoint updates an order with shipping courier information. The
        Cash App Afterpay team may use this information when providing support.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 20             |
      tags:
        - []
      parameters:
        - name: orderId
          in: path
          description: The unique Cash App Afterpay Order ID to update.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            $ref: '#/components/schemas/V2PaymentsOrderIdCourierPutParametersAccept'
      responses:
        '200':
          description: Returns a Payment object in response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '412':
          description: >-
            No Cash App Afterpay Order was found matching the `orderId`
            provided. Error code `precondition_failed`.
          content: {}
        '422':
          description: >-
            A value for shippedAt was provided, but not a valid [ISO
            8601](https://www.iso.org/iso-8601-date-and-time-format.html) date.
            Or, a value for priority was provided, but wasn't one of "STANDARD"
            or "EXPRESS". Error code `invalid_object`.
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shipping-Courier'
components:
  schemas:
    V2PaymentsOrderIdCourierPutParametersAccept:
      type: string
      enum:
        - value: application/json
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier';
const options = {
  method: 'PUT',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier");
var request = new RestRequest(Method.PUT);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/orderId/courier")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create Refund

POST https://global-api-sandbox.afterpay.com/v2/payments/{orderId}/refund
Content-Type: application/json

This endpoint performs a full or partial refund. The refund operation is idempotent if a unique `requestId` and `merchantReference` are provided.

If using the Deferred Payment Flow, be aware that only captured funds can be refunded. Do not create refunds after 120 days from the date of purchase.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 70             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/create-refund

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create Refund
  version: endpoint_.create-refund
paths:
  /v2/payments/{orderId}/refund:
    post:
      operationId: create-refund
      summary: Create Refund
      description: >
        This endpoint performs a full or partial refund. The refund operation is
        idempotent if a unique `requestId` and `merchantReference` are provided.


        If using the Deferred Payment Flow, be aware that only captured funds
        can be refunded. Do not create refunds after 120 days from the date of
        purchase.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 70             |
      tags:
        - []
      parameters:
        - name: orderId
          in: path
          description: The unique Cash App Afterpay Order ID to apply the refund to.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: >
            Returns a Refund object in response. All request parameters are
            echoed in the response. In addition, the response includes the
            following:

            | Attribute | Type | Description |

            | --- | --- | --- |

            | `refundId` | string | The unique, permanent, Cash App
            Afterpay-generated Refund ID. |

            | `refundedAt` | string | The UTC timestamp of when the refund was
            completed, in [ISO
            8601](https://www.iso.org/iso-8601-date-and-time-format.html)
            format. |
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '412':
          description: >-
            The `orderId` is invalid, does not exist, or is not eligible for a
            refund. For example, the order was declined. Error code
            `precondition_failed`.
          content: {}
        '422':
          description: >
            | errorCode | Description |

            | --- | --- |

            | invalid_object | The `refundMerchantReference` exceeded 128
            characters. |

            | invalid_amount | The `amount` requested exceeded the amount
            available. |

            | invalid_object | The currency of the refund does not match the
            currency of the order (and the Merchant account). |

            | refund_timelimit_exceeded | The refund exceeds the time limit of
            120 days. |
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefund'
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    CreateRefund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund"

payload = {
    "requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a",
    "amount": {
        "amount": "10.00",
        "currency": "AUD"
    },
    "merchantReference": "merchantRefundId-1234",
    "refundMerchantReference": "merchantRefundId-1234",
    "refundId": "67890123",
    "refundedAt": "2023-01-01T00:00:00.000Z"
}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{"requestId":"49efce77-4bf2-4e41-86e8-c2b92f493c2a","amount":{"amount":"10.00","currency":"AUD"},"merchantReference":"merchantRefundId-1234","refundMerchantReference":"merchantRefundId-1234","refundId":"67890123","refundedAt":"2023-01-01T00:00:00.000Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund"

	payload := strings.NewReader("{\n  \"requestId\": \"49efce77-4bf2-4e41-86e8-c2b92f493c2a\",\n  \"amount\": {\n    \"amount\": \"10.00\",\n    \"currency\": \"AUD\"\n  },\n  \"merchantReference\": \"merchantRefundId-1234\",\n  \"refundMerchantReference\": \"merchantRefundId-1234\",\n  \"refundId\": \"67890123\",\n  \"refundedAt\": \"2023-01-01T00:00:00.000Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requestId\": \"49efce77-4bf2-4e41-86e8-c2b92f493c2a\",\n  \"amount\": {\n    \"amount\": \"10.00\",\n    \"currency\": \"AUD\"\n  },\n  \"merchantReference\": \"merchantRefundId-1234\",\n  \"refundMerchantReference\": \"merchantRefundId-1234\",\n  \"refundId\": \"67890123\",\n  \"refundedAt\": \"2023-01-01T00:00:00.000Z\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestId\": \"49efce77-4bf2-4e41-86e8-c2b92f493c2a\",\n  \"amount\": {\n    \"amount\": \"10.00\",\n    \"currency\": \"AUD\"\n  },\n  \"merchantReference\": \"merchantRefundId-1234\",\n  \"refundMerchantReference\": \"merchantRefundId-1234\",\n  \"refundId\": \"67890123\",\n  \"refundedAt\": \"2023-01-01T00:00:00.000Z\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund', [
  'body' => '{
  "requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a",
  "amount": {
    "amount": "10.00",
    "currency": "AUD"
  },
  "merchantReference": "merchantRefundId-1234",
  "refundMerchantReference": "merchantRefundId-1234",
  "refundId": "67890123",
  "refundedAt": "2023-01-01T00:00:00.000Z"
}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requestId\": \"49efce77-4bf2-4e41-86e8-c2b92f493c2a\",\n  \"amount\": {\n    \"amount\": \"10.00\",\n    \"currency\": \"AUD\"\n  },\n  \"merchantReference\": \"merchantRefundId-1234\",\n  \"refundMerchantReference\": \"merchantRefundId-1234\",\n  \"refundId\": \"67890123\",\n  \"refundedAt\": \"2023-01-01T00:00:00.000Z\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [
  "requestId": "49efce77-4bf2-4e41-86e8-c2b92f493c2a",
  "amount": [
    "amount": "10.00",
    "currency": "AUD"
  ],
  "merchantReference": "merchantRefundId-1234",
  "refundMerchantReference": "merchantRefundId-1234",
  "refundId": "67890123",
  "refundedAt": "2023-01-01T00:00:00.000Z"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/orderId/refund")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Void

POST https://global-api-sandbox.afterpay.com/v2/payments/{orderId}/void
Content-Type: application/json

This endpoint voids the remaining `openToCapture` amount of the payment auth, and refunds the customer.

<Info title="Note">
  To make a partial void, specify an amount in the request body. 
</Info>

This operation is idempotent based on the `requestId` (if provided), which allows for the safe retry of multiple requests, guaranteeing the payment operation is only made once.




**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 70             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/void-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Void
  version: endpoint_.void-payment
paths:
  /v2/payments/{orderId}/void:
    post:
      operationId: void-payment
      summary: Void
      description: >
        This endpoint voids the remaining `openToCapture` amount of the payment
        auth, and refunds the customer.


        <Info title="Note">
          To make a partial void, specify an amount in the request body. 
        </Info>


        This operation is idempotent based on the `requestId` (if provided),
        which allows for the safe retry of multiple requests, guaranteeing the
        payment operation is only made once.





        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 70             |
      tags:
        - []
      parameters:
        - name: orderId
          in: path
          description: >-
            The unique ID of the Cash App Afterpay Order, returned as the `id`
            property of the Auth response.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '201':
          description: >
            If successful, returns an updated copy of the Payment object.

            - A new Payment Event object is appended to the events array, with a
            type of "VOIDED".

            - A new Refund object is prepended to the refunds array.

            - If the openToCapture amount is reduced to zero as a result of this
            Void request, the paymentState is updated as follows:
              - from "AUTH_APPROVED" to "VOIDED", or
              - from "PARTIALLY_CAPTURED" to "CAPTURED".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          description: >-
            The `orderId` string provided was empty or did not match a valid
            order. Error code `not_found`.
          content: {}
        '422':
          description: >
            The amount in USD has exceeded the open-to-capture amount in USD.
            Example message: "Void amount USD 999.00 exceeded open to capture
            amount USD 40.00." Error code `invalid_amount`.
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  $ref: '#/components/schemas/Money'
                  description: >-
                    The amount to void. Must be less than or equal to the open
                    to capture amount.
                requestId:
                  type: string
                  description: >-
                    A unique request ID, required for safe retries. It is
                    recommended that the merchant generate a UUID for each
                    unique void.
                reason:
                  type: string
                  description: >-
                    Can be passed in void requests to conditionally modify
                    wording of the corresponding customer refund email. This can
                    be set to 1 of 3 values, `cancelledItems`,
                    `amountAdjustment` or `null`
components:
  schemas:
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/orderId/void"

payload = {}
headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/void';
const options = {
  method: 'POST',
  headers: {
    'User-Agent': 'User-Agent',
    Authorization: 'Basic <username>:<password>',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/orderId/void"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/orderId/void")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/orderId/void")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/orderId/void', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/orderId/void");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/orderId/void")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Get Payment By Token

GET https://global-api-sandbox.afterpay.com/v2/payments/token:{token}

This endpoint retrieves an individual payment along with its order details.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 20             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/get-payment-by-token

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Get Payment By Token
  version: endpoint_.get-payment-by-token
paths:
  /v2/payments/token:{token}:
    get:
      operationId: get-payment-by-token
      summary: Get Payment By Token
      description: >
        This endpoint retrieves an individual payment along with its order
        details.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 20             |
      tags:
        - []
      parameters:
        - name: token
          in: path
          description: Order token that was used to complete payment.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: Returns a Payment object in response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          description: >-
            No Cash App Afterpay Order was found matching the `token` provided.
            Error code `not_found`.
          content: {}
components:
  schemas:
    PaymentStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
    MoneyCurrency:
      type: string
      enum:
        - value: AUD
        - value: NZD
        - value: USD
        - value: CAD
        - value: GBP
    Money:
      type: object
      properties:
        amount:
          type: string
          description: >-
            The amount as a string representation of a decimal number, rounded
            to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
        - amount
        - currency
    PaymentPaymentState:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: PARTIALLY_CAPTURED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: >-
            The merchant’s internal refund id/reference. This must be included
            along with the `requestId` to utilise idempotency. Max length 85
            (varchar).
        refundMerchantReference:
          type: string
          description: >-
            A unique reference for the individual refund event. Max length 128
            (varchar).
        refundId:
          type: string
          description: The unique, permanent, Cash App Afterpay-generated Refund ID.
        refundedAt:
          type: string
    Consumer:
      type: object
      properties:
        email:
          type: string
          format: email
        givenNames:
          type: string
          description: The consumer's first name
        surname:
          type: string
          description: The consumer's last name
        phoneNumber:
          type: string
      required:
        - email
    ContactCountryCode:
      type: string
      enum:
        - value: AU
        - value: NZ
        - value: US
        - value: CA
        - value: GB
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: |-
            - AU: Suburb
            - NZ: Town or City
            - UK: Postal Town
            - US: City
            - Canada: City
        area2:
          type: string
          description: |-
            - NZ: suburb
            - UK: village or local area.
        region:
          type: string
          description: |-
            - AU: State 
            - NZ: Region
            - UK: County
            - US: State
            - CA: Province or Territory
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: >-
            The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123)
            format.
      required:
        - name
        - line1
        - area1
        - region
        - postcode
        - countryCode
    ShippingCourierPriority:
      type: string
      enum:
        - value: STANDARD
        - value: EXPRESS
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
        - name
        - quantity
        - price
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
    PaymentEventType:
      type: string
      enum:
        - value: AUTH_APPROVED
        - value: AUTH_DECLINED
        - value: CAPTURED
        - value: CAPTURE_DECLINED
        - value: VOIDED
        - value: EXPIRED
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Cash App Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: >-
            is the merchant's order id/reference that the payment corresponds
            to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/token:token"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/token:token';
const options = {
  method: 'GET',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/token:token"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/token:token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/v2/payments/token:token")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/v2/payments/token:token', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/token:token");
var request = new RestRequest(Method.GET);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/token:token")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Reverse Payment By Token

POST https://global-api-sandbox.afterpay.com/v2/payments/token:{token}/reversal

This endpoint makes a reversal of the checkout that is used to start the Cash App Afterpay payment process. This cancels the order asynchronously as soon as it is created without the need of an additional call to the void endpoint. For a payment to be eligible, the order must be in an Auth-Approved or Captured state, and it must be issued within 10 minutes of the order being created.

**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 70             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/payments/reverse-payment-by-token

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Reverse Payment By Token
  version: endpoint_.reverse-payment-by-token
paths:
  /v2/payments/token:{token}/reversal:
    post:
      operationId: reverse-payment-by-token
      summary: Reverse Payment By Token
      description: >
        This endpoint makes a reversal of the checkout that is used to start the
        Cash App Afterpay payment process. This cancels the order asynchronously
        as soon as it is created without the need of an additional call to the
        void endpoint. For a payment to be eligible, the order must be in an
        Auth-Approved or Captured state, and it must be issued within 10 minutes
        of the order being created.


        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 70             |
      tags:
        - []
      parameters:
        - name: token
          in: path
          description: The token of the checkout to be reversed (voided).
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Basic authentication of the form `Basic <username:password>`.
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: application/json
      responses:
        '204':
          description: >-
            The Reversal endpoint indicates a successful response with a 204
            status code response. Returns no content in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reverse-payment-by-token_Response_204'
        '402':
          description: Invalid Token. Error code `invalid_token`.
          content: {}
        '412':
          description: >
            | errorCode | Description |

            | --- | --- |

            | precondition_failed | Payment reversal previously processed |

            | precondition_failed | Payment not eligible for a reversal |

            | precondition_failed | Order outside reversal window |

            | precondition_failed | Order in pending reversal, no captures/auth
            accepted |
          content: {}
components:
  schemas:
    reverse-payment-by-token_Response_204:
      type: object
      properties: {}

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal"

headers = {
    "User-Agent": "User-Agent",
    "Authorization": "Basic <username>:<password>"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal';
const options = {
  method: 'POST',
  headers: {'User-Agent': 'User-Agent', Authorization: 'Basic <username>:<password>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Authorization", "Basic <username>:<password>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["User-Agent"] = 'User-Agent'
request["Authorization"] = 'Basic <username>:<password>'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal")
  .header("User-Agent", "User-Agent")
  .header("Authorization", "Basic <username>:<password>")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal', [
  'headers' => [
    'Authorization' => 'Basic <username>:<password>',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal");
var request = new RestRequest(Method.POST);
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Authorization", "Basic <username>:<password>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "User-Agent": "User-Agent",
  "Authorization": "Basic <username>:<password>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/v2/payments/token:token/reversal")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# AuthorizePayment

<EndpointSchemaSnippet endpoint="GET /authorize-payment-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
    "merchantReference": "merchant-order-123",
    "amount": {
      "amount": "100.00",
      "currency": "AUD"
    },
    "isCheckoutAdjusted": true,
    "paymentScheduleChecksum": "string",
    "items": [],
    "shipping": {
      "name": "Joe Consumer",
      "line1": "Level 5",
      "line2": "390 Collins Street",
      "area1": "Melbourne",
      "region": "VIC",
      "postcode": "3000",
      "countryCode": "AU",
      "phoneNumber": "0400 000 000"
    },
    "enrichments": {
      "initiation": {
        "actor": "CUSTOMER"
      },
      "subscription": {
        "type": "FIXED",
        "interval": "DAY",
        "intervalCount": 1
      }
    }
  }
  ```
</Aside>

---

# CapturePayment

<EndpointSchemaSnippet endpoint="GET /capture-payment-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
    "merchantReference": "merchant-order-123",
    "amount": {
      "amount": "100.00",
      "currency": "AUD"
    },
    "paymentEventMerchantReference": "payment-ref-123"
  }
  ```
</Aside>

---

# Ping

GET https://global-api-sandbox.afterpay.com/ping

Use this endpoint to check that the service is available and reachable.

Unlike all other endpoints, this endpoint does not require authentication, and responds with `text/plain` instead of `application/json`.


**Connection Timeouts**
| Timeout | Time (Seconds) |
|---------|----------------|
| Open    | 10             |
| Read    | 20             |


Reference: https://developers.cash.app/cash-app-afterpay/api-reference/reference/service-status/ping

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Ping
  version: endpoint_.ping
paths:
  /ping:
    get:
      operationId: ping
      summary: Ping
      description: >
        Use this endpoint to check that the service is available and reachable.


        Unlike all other endpoints, this endpoint does not require
        authentication, and responds with `text/plain` instead of
        `application/json`.



        **Connection Timeouts**

        | Timeout | Time (Seconds) |

        |---------|----------------|

        | Open    | 10             |

        | Read    | 20             |
      tags:
        - []
      parameters:
        - name: Accept
          in: header
          required: false
          schema:
            type: string
            default: text/plain
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '405':
          description: >-
            The request was made by a HTTP Method other than `GET`, `HEAD` or
            `OPTIONS`. For example, `POST`, `PUT` or `DELETE`.
          content: {}

```

## SDK Code Examples

```python
import requests

url = "https://global-api-sandbox.afterpay.com/ping"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://global-api-sandbox.afterpay.com/ping';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://global-api-sandbox.afterpay.com/ping"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://global-api-sandbox.afterpay.com/ping")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://global-api-sandbox.afterpay.com/ping")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://global-api-sandbox.afterpay.com/ping');

echo $response->getBody();
```

```csharp
var client = new RestClient("https://global-api-sandbox.afterpay.com/ping");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://global-api-sandbox.afterpay.com/ping")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Contact object

```yaml json_schema
$ref: "../../models/Contact.yaml"
```

## Example Contact object

```json Contact Object
{
  "name": "Joe Customer",
  "line1": "3655 Lawton St",
  "area1": "San Francisco",
  "region": "CA",
  "postcode": "94122",
  "countryCode": "US",
  "phoneNumber": "(415) 200-0000"
}
```

---

# Consumer object

```yaml json_schema
$ref: "../../models/Consumer.yaml"
```

## Example Consumer object

```json
{
  "phoneNumber": "(415) 200-0000",
  "givenNames": "Joe",
  "surname": "Customer",
  "email": "test@example.com"
}
```

---

# Discount object

## Attributes

| Attribute   | Type                                                                         | Status   | Description                                                 |
| ----------- | ---------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| displayName | string                                                                       | required | A display name for the discount. Limited to 128 characters. |
| amount      | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object) | required | The discount amount.                                        |

## Example Discount object

```json
{
  "displayName": "New Customer Coupon",
  "amount": {
    "amount": "29.99",
    "currency": "USD"
  }
}
```

---

# Item object

## Attributes

| Attribute             | Type                                                                         | Status   | Description                                                                                                                                                                                             |
| --------------------- | ---------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                  | string                                                                       | required | Product name. Limited to 255 characters.                                                                                                                                                                |
| sku                   | string                                                                       |          | Product SKU. Limited to 128 characters.                                                                                                                                                                 |
| quantity              | integer                                                                      | required | The quantity of the item, stored as a signed 32-bit integer.                                                                                                                                            |
| pageUrl               | string                                                                       |          | The canonical URL for the item's Product Detail Page. Limited to 2048 characters.                                                                                                                       |
| imageUrl              | string                                                                       |          | A URL for a web-optimised photo of the item, suitable for use directly as the `src` attribute of an `img` tag. Limited to 2048 characters.                                                              |
| price                 | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object) | required | The unit price of the individual item. Must be a positive value.                                                                                                                                        |
| categories            | \[]                                                                          |          | An array of arrays to accommodate multiple categories that apply to the item. Each array represents a hierarchical path to a category, with the left-most category being the top-level parent category. |
| estimatedShipmentDate | string                                                                       |          | The estimated date when the order will be shipped, in YYYY-MM or YYYY-MM-DD format.                                                                                                                     |
| preorder              | boolean                                                                      |          | If this item is not expected to be fulfilled immediately, and therefore should be marked as a preorder at checkout, set to `true`. Set to `false` otherwise.                                            |

## Example Item object

```json
{
  "name": "Blue Carabiner",
  "sku": "12341234",
  "quantity": 1,
  "pageUrl": "https://merchant.example.com/carabiner-354193.html",
  "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
  "price": {
    "amount": "40.00",
    "currency": "USD"
  },
  "categories": [
    ["Sporting Goods", "Climbing Equipment", "Climbing", "Climbing Carabiners"],
    ["Sale", "Climbing"]
  ],
  "estimatedShipmentDate": "2024-03-01"
}
```

---

# Money object

## Attributes

| Attribute | Type   | Status   | Description                                                                                                                                                                                                        |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| amount    | string | required | The amount is a string representation of a decimal number, rounded to 2 decimal places.                                                                                                                            |
| currency  | string | required | The currency in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported values include "USD". However, the value provided must correspond to the currency of the Merchant account making the request. |

## 422 Errors

Where a Money object is included in an API request, it will be validated according to the specification above. Invalid Money objects will trigger a **422 Unprocessable Entity response**. The following is a list of common examples.

| Example                                                                              | errorCode              | message                                                                    |
| ------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------- |
| `amount` is omitted or null                                                          | invalid\_object        | `{Money object}.amount` Amount field required                              |
| `amount` has more than 2 decimal places                                              | invalid\_object	amount | must be a valid ISO 4217 format value                                      |
| `amount` includes a thousands separator comma, for example: "1,000"                  | invalid\_amount        | Amount must be a valid ISO 4217 format value                               |
| `amount` is not a decimal number, for example: "FREE", "\$2" or an empty string      | invalid\_object        | `{Money object}.amount` Amount field must be a valid ISO 4217 format value |
| `currency` is omitted or null                                                        | invalid\_object        | `{Money object}.currency` Currency field required                          |
| `currency` is not a valid currency code, not all uppercase or an empty string        | invalid\_object        | `{Money object}.currency` Currency not supported for this merchant         |
| `currency` is supported by Cash App Afterpay, but not valid for the Merchant account | unsupported\_currency  | An error occurred                                                          |

## Example Money object

```json
{
  "amount": "29.99",
  "currency": "USD"
}

```

---

# Order Details object

## Attributes

| Attribute      | Type                                                                                               | Description                                            |
| -------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| consumer       | [Consumer](/cash-app-afterpay/api-reference/reference/data-models/consumer-object)(required)       | The customer who placed or is placing the order.       |
| billing        | [Contact](/cash-app-afterpay/api-reference/reference/data-models/contact-object)                   | The customer's billing address.                        |
| shipping       | [Contact](/cash-app-afterpay/api-reference/reference/data-models/contact-object)                   | The customer's shipping address.                       |
| courier        | [Shipping Courier](/cash-app-afterpay/api-reference/reference/data-models/shipping-courier-object) | The customer's chosen shipping courier.                |
| items          | [Item](/cash-app-afterpay/api-reference/reference/data-models/item-object)                         | An array of order items.                               |
| discounts      | [Discount](/cash-app-afterpay/api-reference/reference/data-models/discount-object)                 | An array of discounts.                                 |
| taxAmount      | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object)                       | The included tax amount, after applying all discounts. |
| shippingAmount | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object)                       | The shipping price charged to the customer.            |

## Example Order Details object

```
{
  "consumer": {  
    "phoneNumber": "(415) 200-0000",
    "givenNames": "Joe",
    "surname": "Customer",
    "email": "test@example.com"
  },
  "billing": {
    "name": "Joe Customer",
    "line1": "3655 Lawton St",
    "area1": "San Francisco",
    "region": "CA",
    "postcode": "94122",
    "countryCode": "US",
    "phoneNumber": "(415) 200-0000"
  },
  "shipping": {
    "name": "Joe Customer",
    "line1": "3655 Lawton St",
    "area1": "San Francisco",
    "region": "CA",
    "postcode": "94122",
    "countryCode": "US",
    "phoneNumber": "(415) 200-0000"
  },
  "courier" : {
    "shippedAt" : "2024-01-01T00:00:00-08:00",
    "name" : "FedEx",
    "tracking" : "000 000 000 000",
    "priority" : "STANDARD"
  },
  "items": [  
    {
      "name": "Blue Carabiner",
      "sku": "12341234",
      "quantity": 1,
      "pageUrl": "https://merchant.example.com/carabiner-354193.html",
      "imageUrl": "https://merchant.example.com/carabiner-7378-391453-1.jpg",
      "price": {
        "amount": "40.00",
        "currency": "USD"
      },
      "categories": [
        ["Sporting Goods", "Climbing Equipment", "Climbing", "Climbing Carabiners"],
        ["Sale", "Climbing"]
      ]
    },
    {
      "name": "LED Lantern",
      "sku": "12346789",
      "quantity": 1,
      "pageUrl": "https://merchant.example.com/lantern-836599.html",
      "imageUrl": "https://merchant.example.com/lantern-3417-983451-1.jpg",
      "price": {
        "amount": "60.00",
        "currency": "USD"
      },
      "categories": [
        ["Camping & Outdoor", "Lighting", "Lanterns"]
      ]
    }
  ],
  "discounts": [
    {
      "displayName": "10% Off Subtotal",
      "amount": {
        "amount": "10.00",
        "currency": "USD"
      }
    }
  ],
  "taxAmount": {  
    "amount": "0.00",
    "currency": "USD"
  },
  "shippingAmount": {  
    "amount": "20.00",
    "currency": "USD"
  }
}

```

---

# Payment object

## Attributes

| Attribute           | Type                                                                                         | Description                                                                                                                                                                                                                               |
| ------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                  | string                                                                                       | The unique, permanent, Cash App Afterpay-generated Order ID.                                                                                                                                                                              |
| token               | string                                                                                       | Checkout token that was used to complete payment.                                                                                                                                                                                         |
| status              | string                                                                                       | An order status of "APPROVED" or "DECLINED".                                                                                                                                                                                              |
| created             | string                                                                                       | The UTC timestamp of when the payment was completed, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.                                                                                                        |
| originalAmount      | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object)                 | Total amount charged to the customer for the order.                                                                                                                                                                                       |
| openToCaptureAmount | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object)                 | Remaining amount that can be captured. Will always be zero for immediate payment flow orders.                                                                                                                                             |
| paymentState        | string                                                                                       | Current state for capturing payments. Will be one of: "AUTH\_APPROVED", "AUTH\_DECLINED", "PARTIALLY\_CAPTURED", "CAPTURED", "CAPTURE\_DECLINED","VOIDED".                                                                                |
| merchantReference   | string                                                                                       | The merchant's order id/reference that this payment corresponds to.                                                                                                                                                                       |
| refunds             | [Refund](/cash-app-afterpay/api-reference/reference/data-models/refund-object)               | An array of refunds. Note: in response to a [Capture Full Payment](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment) call, this array will always be empty, since refunds cannot occur until payment is captured. |
| orderDetails        | [Order Details](/cash-app-afterpay/api-reference/reference/data-models/order-details-object) | The details of the order bound to the payment.                                                                                                                                                                                            |
| events              | [Payment Event](/cash-app-afterpay/api-reference/reference/data-models/payment-event-object) | One or more payment events that have occurred against the order.                                                                                                                                                                          |

Link to [Capture Full Payment](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment)

## Example Payment object

```json
{
  "id" : "12345678",
  "token" : "ltqdpjhbqu3veqikk95g7p3fhvcchfvtlsiobah3u4l5nln8gii9",
  "status" : "APPROVED",
  "created" : "2024-01-01T00:00:00.000Z",
  "originalAmount" : {
    "amount" : "100.00",
    "currency" : "USD"
  },
  "openToCaptureAmount" : {
    "amount" : "100.00",
    "currency" : "USD"
  },
  "paymentState" : "AUTH_APPROVED",
  "merchantReference" : "merchantOrderId-1234",
  "refunds" : [
    ...
  ],
  "orderDetails" : {
    ...
  },
  "events" : [ {
    "id" : "1OUR16OTqL3DgJ3ELlwKowU9v6K",
    "created" : "2024-01-01T00:00:00.000Z",
    "expires" : "2024-01-01T00:00:00.000Z",
    "type" : "AUTH_APPROVED",
    "amount" : {
      "amount" : "100.00",
      "currency" : "USD"
    }
  }, ... ]
}
```

---

# Payment Event object

## Attributes

| Attribute                     | Type                                                                         | Description                                                                                                                                                                                                                                            |
| ----------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id                            | string                                                                       | The unique, Cash App Afterpay-generated event ID.                                                                                                                                                                                                      |
| created                       | string                                                                       | A UTC timestamp of the event creation time, in ISO 8601 format.                                                                                                                                                                                        |
| expires                       | string                                                                       | A UTC timestamp of the "AUTH\_APPROVED" event expiration time, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Null for other event types.                                                                               |
| type                          | string                                                                       | The event type. Will be one of: "AUTH\_APPROVED", "AUTH\_DECLINED", "CAPTURED", "CAPTURE\_DECLINED", "VOIDED", "EXPIRED".                                                                                                                              |
| amount                        | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object) | The amount associated with the event.                                                                                                                                                                                                                  |
| paymentEventMerchantReference | string                                                                       | A unique reference for an individual payment capture event. If provided on [Capture Full Payment](/cash-app-afterpay/api-reference/reference/payments/capture-full-payment), the value will appear in the daily settlement file as "Payment Event ID". |

## Example Payment Event object

```json
{
  "id" : "1OUR16OTqL3DgJ3ELlwKowU9v6K",
  "created" : "2024-01-01T00:00:00.000Z",
  "expires" : "2024-01-01T00:00:00.000Z",
  "type" : "AUTH_APPROVED",
  "amount" : {
    "amount" : "100.00",
    "currency" : "USD"
  },
  "paymentEventMerchantReference" : null
}
```

---

# Refund object

## Attributes

| Attribute               | Type                                                                                    | Description                                                                                                                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| requestId               | string                                                                                  | A unique request ID, required (in conjunction with `merchantReference`) for safe retries. We recommend that merchants generate a UUID for each unique refund. Max character length = 64.                                                |
| amount                  | [Money](/cash-app-afterpay/api-reference/reference/data-models/money-object) (required) | The refund amount.                                                                                                                                                                                                                      |
| merchantReference       | string                                                                                  | The merchant's corresponding refund ID or reference, required (in conjunction with `requestId`) for safe retries. Max character length = 64.                                                                                            |
| refundId                | string                                                                                  | The unique, Cash App Afterpay-generated refund ID.                                                                                                                                                                                      |
| refundedAt              | string                                                                                  | A UTC timestamp of the refund creation time, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.                                                                                                              |
| refundMerchantReference | string                                                                                  | A unique reference for the individual refund event. If provided, the value appears in the daily settlement file as "Payment Event ID". In most cases, this holds the same value as the `merchantReference`. Max character length = 128. |

## Example Refund object

```json
{
  "requestId" : "956946da-4863-4797-aa7c-540050faf922",
  "amount" : {  
    "amount" : "10.00",
    "currency" : "USD"
  },
  "merchantReference" : "merchantRefundId-1234",
  "refundId" : "67890123",
  "refundedAt" : "2024-01-01T00:00:00.000Z",
  "refundMerchantReference" : "merchantRefundId-1234"
}
```

---

# Shipping Courier object

## Attributes

| Attribute | Type   | Description                                                                                                                 |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| shippedAt | string | The date and time when the order was shipped, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. |
| name      | string | The name of the courier. This is limited to 128 characters.                                                                 |
| tracking  | string | The tracking number provided by the courier. Limited to 128 characters.                                                     |
| priority  | string | The shipping priority. If provided, must be either "STANDARD" or "EXPRESS".                                                 |

## Example Shipping Courier object

```json
{
  "shippedAt": "2024-01-01T00:00:00-08:00",
  "name": "FedEx",
  "tracking": "000 000 000 000",
  "priority": "STANDARD"
}
```

---

# Welcome

{/* <div style="width:87%;">
  <div 
      style="
          display: flex; 
          flex-direction: row; 
          align-items: center;
          justify-content: space-between; 
          background-color: #00D64F; 
          border-radius: 16px;
          margin-top: 0.3rem;
          margin-bottom: 10rem;
          max-height: 190px;
      "
  >
      <div 
          style="
              display: flex;
              flex-direction: row;
              align-items: center;
              gap: 16px;
              padding: 24px 0 24px 48px;
          "
      >
        <div style="display: flex; flex-direction: column; gap: 4px;">
          <h1 style="line-height: 30px; font-size: 30px; font-weight: 700">
            Welcome Cash App Pay to your checkout
          </h1>
        </div>
      </div>
      <div 
        style="
          transform: translateX(50%) translateY(35%);
          flex: 1 0.5 310px;
        "
      >
          <img 
              src="../assets/images/cash-app-pay-landing-hero.png" 
              alt="cash-app-pay-splash" noZoom
              style="max-width: 310px; width: 100%;"
          />
      </div>
  </div> */}

<p>
  <br />

  Welcome to the Cash App Pay developer documentation. Here you'll find comprehensive guides, API references, and integration tools to help you implement Cash App Pay.

  Our documentation includes detailed API specifications, step-by-step integration guides, testing environments, and best practices to ensure a smooth implementation process. Whether you're building a new integration or optimizing an existing one, you'll find the resources you need to create a seamless payment experience for your customers.

  <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/content - showcase messaging.png" alt="convergence-splash" noZoom />
</p>

{/* </div> */}

---

# How Cash App Pay Works

Cash App currently supports three main use cases:

* Mobile-Ecommerce
* Web-Ecommerce
* POS (Point-of-Sale)

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/how-cash-app-pay-works.png" alt="How Cash App Pay Works" noZoom />

<br />

---

# Mobile-Ecommerce

The Customer visits a mobile ecommerce app(or site) and uses their Cash App to pay for goods and services.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/mobile-ecom-flow.png" alt="Ecommerce web workflow: choose a product, checkout, add shipping address, select paymnet method, link Cash App Pay, complete purchase" noZoom />

<br />

<br />

---

# Web-Ecommerce

The Customer visits a web-based ecommerce site and pays for items by scanning the QR code generated at checkout using Cash App on their phone.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/ecom-web-flow.png" alt="Ecommerce web workflow: choose a product, checkout, scan a QR code, link Cash App Pay, complete purchase" noZoom />

<br />

<br />

---

# POS

Customer goes to a merchant and uses a Point-of-Sale (POS) device, for example, like the Square POS device.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/pos-flow.png" alt="POS workflow: choose a product, checkout, scan a QR code, link Cash App Pay, complete purchase" noZoom />

<br />

<br />

To learn more about how Cash App Pay works on different devices, see the following:

* [Cash App Pay on Mobile devices](/cash-app-pay-partner-api/guides/product-overview/cash-app-pay-on-mobile-devices)
* [Cash App Pay on Desktop and POS devices](/cash-app-pay-partner-api/guides/product-overview/cash-app-pay-on-desktop-and-pos-devices)

---

# Cash App Pay on Desktop and POS devices

![Web-POS Experience Diagram](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/web-pos-experience.png)

Customers can use Cash App Pay at the Merchant’s physical locations or during ecommerce checkouts using a Laptop or Desktop computer. The customer linking process consists of three-steps as follows:

1. The Customer chooses **Cash App Pay** as their payment method at checkout (on the Merchant’s POS (Point-of-Sale) device or Customer’s desktop/laptop)

   <Note>
      POS devices can be tablets or desktop devices
   </Note>

   ![Customer chooses Cash App Pay](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/demo-customer-chooses-cash-app-pay.png)

2. A QR code pops up on the screen. The Customer scans the QR code using their Cash App or the camera on their mobile device.

   ![QR Code is displayed](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/demo-qr-code-displayed.png)

3. The Customer approves the payment when they scan the QR code with Cash App or the camera on their mobile device.

   ![Customer scans to pay](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/demo-customer-scans-to-pay.png)

---

# Cash App Pay on Mobile devices

![Mobile Experience](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/mobile-experience.png)

When doing online shopping on their mobile devices (both Android and Apple) and Android tablets, the Customer can use Cash App Pay as their payment method. This is also a simple three-step process for the Customer and is as follows:

1. At checkout, the Customer chooses Cash App Pay as their payment method.

   ![Customer chooses Cash App Pay](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/demo-mobile-customer-chooses-cash-app-pay.png)

2. The Customer is redirected to Cash App, where the Merchant’s Business Name and Logo, transaction amount (optional), and Continue to checkout button is displayed.

   ![Customer redirected to Cash App](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/demo-mobile-redirect-to-cash-app.png)

3. The Customer selects Continue to checkout in Cash App and is automatically redirected to the Merchant's online store. Cash App Pay is displayed as the selected payment method. The Customer can also see their Cashtag displayed next to the Cash App Pay logo and brand. From here, they complete their purchase as usual.

   ![Customer continues to checkout](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/demo-mobile-continue-checkout.png)

   <Note>
     The Customer can also be redirected directly to the order confirmation page of the Merchant.
   </Note>

   <Note>
     If you are using React Native applications in your development, there are some extra configurations that are required for iOS and Android. See [React Native Requirements](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/react-native-requirements) for more details.
   </Note>

---

# Partner with Cash App Pay

Cash App Pay partners with Payment Service Providers (PSPs) and select e-commerce platforms.

To integrate with Cash App Pay, prospective partners must go through an approval process, where we determine your goals and requirements. Once you're approved, we provision a developer account for you.

For information on how to partner with Cash App Pay, please reach out to the [Cash App Pay Partner Engineering Team](https://afterpay.formstack.com/forms/global_merchant_technical_support).

## Partner deliverables

Cash App Pay’s Partner Engineering team will configure and provide you with the following:

* **Developer account:** A developer account with the account configuration details that you provided
* **API access:** A Client ID and API Key that allow you to access our APIs
  * **ClientID:** A short application identifier that Cash App Pay uses to attribute API calls to your integration
  * **API Key (Client Secret):** A long lived secret token that should be stored and transferred securely. Never check it into source control.

## Cash App Pay for merchants

<Warning title="Important">
  This documentation is intended for developers at PSPs and e-commerce platforms. If you're a merchant looking to integrate with Cash App Pay or Cash App Afterpay, please see the 

  [Cash App Afterpay documentation](/cash-app-afterpay/guides/welcome/getting-started)

  .
</Warning>

To add Cash App Pay as a payment method, merchants should [sign up with Afterpay](https://www.afterpay.com/en-US/for-retailers). This gives merchants access to both Cash App Pay and Afterpay.

The following PSPs currently support Cash App Pay:

* [Square](https://developer.squareup.com/docs/web-payments/add-cash-app-pay)
* [Cash App Afterpay](/cash-app-afterpay/guides/api-development/add-cash-app-pay-to-your-site/overview)
* [Stripe](https://stripe.com/docs/payments/cash-app-pay/accept-a-payment)
* [Adyen](https://docs.adyen.com/payment-methods/cash-app-pay)

Merchants can also accept Cash App Pay using the following e-commerce platforms:

* Shopify
* Magento (Adobe Commerce)
* Salesforce Commerce Cloud

---

# Onboarding Requirements

Cash App Pay's Partner engineering team requires the following details from you to complete this integration:

* **Account configuration details:** You must send the Partner Engagement team these details, so that they can get started on creating a developer account for you:

  * **App Display Name:** The formal name of the integration. It should be representative of your brand to preserve continuity between your application and Cash App authorization screens. It is shown to Cash App customers during the Authorization flow and then subsequently in their list of authorized integrations.
  * **App Icon:** It should match graphical assets used for your existing application but formatted to be 512x512, in PNG format and be representative of your brand to preserve continuity between your application and Cash App authorization screens. It is shown to Cash App customers during the Authorization flow and then subsequently in their list of authorized integrations.

* **SFTP server details for settlement configuration:** Cash App settles captured payments with the PSP (Payment Service Provider) via ACH using a batch process. Cash App captures the transaction-level details of each settlement as a reconciliation report and this report is uploaded daily to a client-provided SFTP server.
  To enable this for you, we require the following details:
  * **SFTP Hostname:** The host address for the partner-owned SFTP server.
  * **SFTP Port:** The port for the partner-owned SFTP server.
  * **Username:** The username for the partner-owned SFTP server.
  * **SFTP user’s private key:** The private RSA key of the provided user for the partner-owned SFTP server.
  * **SFTP server host’s public key:** The public RSA key of the server host for the partner-owned SFTP server.
  * **Destination folder path for settlement reports:** The file path where settlement reconciliation files will be uploaded to on a daily basis.(relative path from your home directory)
  * **Destination folder path for dispute reports:** The file path where dispute reconciliation files will be uploaded to on a daily basis.(relative path from your home directory)

* **Bank account details (Production only):** In Production, you must connect a bank account to receive incoming funds. Our Partner Engineers will work directly with you to securely collect and store these details:
  * **Account Name:** The name of the destination bank where the funds will be deposited via ACH (required).
  * **Account Number:** The account number of the destination bank where the funds will be deposited via ACH (required).
  * **Routing Number:** The routing number of the destination bank where the funds will be deposited via ACH (required).
  * **ACH Company ID:** The 10-digit unique identifier used for identifying entities collecting payments via ACH debit.

## Partner Certification

To take payments from Cash App Pay in production, Cash App’s Partner Engineering team will certify your integration to ensure that integration best practices are followed. This ensures that our mutual merchants and customers have a delightful commerce experience while using Cash App Pay.

<Note>
  Ask the Partner Engineering team for the Partner Certification checklist file.
</Note>

---

# Merchant Use Policy

Last update:
May 14, 2024

***

By using Cash App Pay, Merchants and PSPs agree to be bound by the Cash App Pay [Program Rules](/cash-app-pay-partner-api/guides/partnerships/program-rules) and this Cash App Pay Merchant Use Policy (“Policy”). This Policy outlines Transactions that we prohibit in connection with the use of Cash App Pay as well as restricted Transactions that we may permit subject to our prior written consent. This Policy applies to anyone using Cash App Pay, Cash App, or our services, and to any Transaction we are asked to process using Cash App Pay. We may, in our sole judgment and discretion, and for any reason, take any corrective action, including, but not limited to, blocking a Transaction and/or suspending or terminating access and use of Cash App Pay, if we believe a Merchant, PSP, Transaction, or series of Transactions violates this Policy or is otherwise illegal or fraudulent.

Capitalized terms in this Policy that are not defined shall have the meanings set forth in the Cash App Pay Program Rules. We may modify this Policy at any time by posting a revised version on our documentation site. By using Cash App Pay, you agree to the latest version of this Policy.

The categories of prohibited and restricted Transactions listed below are representative, but not exhaustive.

## I. Prohibited Transactions

Except where prohibited by law, Transactions used for, or to facilitate the use of, related to, or to allow others to use CAP are **prohibited**:

|                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Adult Content & Services                | Activity related to pornography, pornographic subscriptions, prostitution, pay-per view, adult live chat, escort or companionship services, or any other obscene materials (including literature, imagery, and other media); any product or service that promotes underage, non-consensual, or other illegal sexual themes.                                                                                                                                                                                                                                                                                                                                                        |
| Consumer Safety                         | Any goods or services that are dangerous, violent, or present an unreasonable risk to consumer safety (e.g., firearms, weapons, explosives, ammunition, and related accessories.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Counterfeit and Stolen                  | Activity related to fraudulent, counterfeit brand name or designer products or services (e.g. knock-offs, imitations, bootlegs); goods or services that are illegal, illegally imported, exported, or stolen, including digital and virtual goods.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Drug Paraphernalia                      | Activity related to narcotics, controlled substances, substances that provide the same effect as an illegal drug (e.g., salvia, kratom), and any equipment designed for making or using drugs, such as bongs, vaporizers, and hookahs. Activity related to pharmacies, pharmaceuticals, pseudo pharmacies (e.g., anti-aging pills, sexual stimulants, weight loss, diet, etc.) or supplements, including internet, mail order, or telephone order pharmacies or pharmacy referral services (where fulfillment of medication is performed with an internet or telephone consultation, absent a physical visit, including re-importation of pharmaceuticals from foreign countries.) |
| Deceptive Products & Services           | Any products or services that are fraudulent, deceptive, or designed to enable dishonest behavior (e.g., academic paper writing and test-taking services, hacking materials, devices for circumventing traffic rules.)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Discrimination & Harassment             | Activity, content, or communications (oral or written) including anything that promotes violence, discrimination, or incites hatred against individuals or groups based on protected characteristics, is explicit, abusive, or hateful. This includes without limitation activities that defame, abuse, extort, harass, stalk, threaten or otherwise violate or infringe the legal rights of others.                                                                                                                                                                                                                                                                               |
| Financial Services                      | Any activity related to providing financial services, including: money services businesses, predatory loans and lending, credit repair and debt relief services, credit protection or identity theft protection services, debt collection services, bail bonds, buyers or membership clubs, peer-to-peer transactions; cryptocurrency activities; broker dealer or registered investment activity; wire transfers or money orders; prepaid cards; gift cards.                                                                                                                                                                                                                      |
| High Risk                               | Activity with elevated financial risk, legal liability, or violates card network rules or bank policies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Illegal                                 | Activity involving unlawful or illegal goods or services, including any federal or state law, statute, regulation, or ordinance. Activity related to bribes and corruption Activity that may be in violation of regulations administered by the United States Department of the Treasury’s Office of Foreign Asset Control (31 C.F.R. Parts 500-599).                                                                                                                                                                                                                                                                                                                              |
| Intellectual Property                   | Activity that violates or infringes on another’s right of privacy, publicity, or intellectual property (patent, copyright, trademark, etc.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Minors                                  | Activity involving child endangerment, including anything that sexualizes minors or appeals to children but contains adult themes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Network Marketing Programs              | Activity related to get-rich-quick schemes, multi-level marketing, pyramid schemes, and ponzi schemes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Prior Written Consent                   | Any Transaction requiring prior written consent without obtaining proper consent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Long Term Subscriptions and Memberships | Activity related to subscriptions or memberships in excess of one year (e.g. 2-year, 3-year, lifetime, etc.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Tobacco                                 | Activity involving tobacco, e-cigs, and vaping.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| International                           | Activity for or related to a business located outside of the 50 states of the United States or an international seller (i.e., a business without an operating entity in one of the 50 states of the United States and a U.S. domestic bank account.). This restriction does not apply to activity for or related to a business located on a U.S. military base, embassy, or consulate on foreign territory or in a U.S. territory or possession.                                                                                                                                                                                                                                   |

## II. Restricted Transactions

Transactions used for, or to facilitate the use of, related to, or to allow others to use CAP for the following activity are restricted and only permitted with our **prior written consent**:

|                           |                                                                                                                                                                                                                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alcoholic Beverages       | Activity related to the sale of alcoholic beverages.                                                                                                                                                                                                                                                    |
| Cannabis                  | Activity related to cannabis, hemp, or other cannabis-related sales.                                                                                                                                                                                                                                    |
| Charities & Organizations | Activities related to charities, religious organizations, and other organizations to ensure legal and legitimate donations and fundraising.                                                                                                                                                             |
| Gambling & Sports Betting | Online gambling, betting, wagering, and fantasy sports, including any activity, whether or not legally defined as gambling, that involves an entry fee and prize(s), such as casino games, games of chance or skill, sports and prop betting, horse racing, lotteries, sweepstakes, and fantasy sports. |
| Prescriptions             | Prescription drugs, medicines, and medical devices.                                                                                                                                                                                                                                                     |
| User-Generated Content    | Activity related to user-generated content and live streaming user-generated content.                                                                                                                                                                                                                   |

---

# Program Rules

Last update: October 1, 2025

## Introduction

Block has established these Program Rules to provide a common set of rules governing a Merchant's use of Cash App Pay, establish the minimum obligations of Merchants using Cash App Pay, and provide a common payment experience for all Merchants using Cash App Pay.

These Rules may be modified by Block at its discretion to ensure the effective operation of Cash App Pay. By using Cash App Pay, Merchants agree to be bound by these Program Rules.

## Program Rules List

Here is the list of topics covered under these Program Rules. You can use the page links or the left-hand navigation to see these topics.

* [Use of Cash App Pay](#use-of-cash-app-pay)
* [Merchant Eligibility](#merchant-eligibility)
* [Payment Limits and Liability](#payment-limits-and-liability)
* [Disputes and Disputed Payments](#disputes-and-disputed-payments)
* [Use of Cash App Marks](#use-of-cash-app-marks)
* [Customer Support](#customer-support)
* [Fees, Taxes, and Incentives](#fees-taxes-and-incentives)
* [Confidentiality and Privacy](#confidentiality-and-privacy)
* [Information Security](#information-security)
* [Enforcement](#enforcement)

## Definitions

Capitalized terms used throughout these Program Rules shall have the following meanings, unless otherwise noted. If the singular is used in these Rules, it means the plural, and the plural means the singular.

| Term                                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Applicable Data Protection Laws** | All applicable federal, state and local laws, rules and regulations of any applicable jurisdiction governing the processing of Personal Information or that otherwise relates to data protection, data security, or Data Security Breach notification obligations for Personal Information.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Applicable Laws**                 | All federal, state and local laws or regulations, network rules, and other legal requirements applicable to Cash App Pay in the respective jurisdictions in which Cash App Pay is provided, including without limitation, money transmission, anti-money laundering, anti-terrorist financing, sanctions (including those administered by the U.S. Department of the Treasury's Office of Foreign Assets Control (OFAC)), privacy, information security, consumer protection, anti-bribery, and anti-corruption laws.                                                                                                                                                                                                          |
| **Block**                           | Block, Inc., and all of its subsidiaries and affiliates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Block Services**                  | Cash App, CAP, the CAP API, and any other Block mobile applications, websites, cloud-based solutions, software, developer kits, APIs, documents, or other Block products and services.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **CAP Brand Guidelines**            | The Cash App Brand Guidelines available at [Cash App Pay Assets](/cash-app-pay-partner-api/guides/resources/cash-app-pay-assets).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **CAP Marks**                       | The Cash App logos and trademark assets set forth in the CAP Brand Guidelines.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Cash App**                        | The Cash App application-based financial platform through which Customers can send peer-to-peer payments, store funds, order physical and virtual debit cards, purchase and store bitcoin, pay Merchants using Cash App Pay, and obtain financial rewards using products or services featured within the application.                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Cash App Account**                | A Cash App account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Cash App Balance**                | The funds a Customer has in their Cash App Account that are available for new transactions and are not subject to pending transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Cash App Pay (CAP)**              | The program made available by Block via the Cash App API that enables Merchants to obtain a Customer's authorization to use the Customer's Cash App Account as a payment method for Transactions with participating Merchants.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Cash App Pay API (CAP API)**      | The Application Program Interface (API) made available by Block to Merchants that enables Merchants to offer Cash App Pay as a Payment method for Customers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Cash App Privacy Notice**         | The Cash App [Privacy Notice](https://cash.app/legal/us/en-us/privacy), as amended by Block from time to time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Customer**                        | A user who has a Cash App Account and uses Cash App Pay to make one or more Payments to a Merchant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Data Security Breach**            | Any breach of confidentiality or other event that compromises the security, confidentiality, or integrity of Personal Information or other Restricted Information (as defined in the Confidentiality Section below), including any loss, misuse, or unauthorized access, disclosure, alteration, destruction or acquisition of Personal Information or other Restricted Information.                                                                                                                                                                                                                                                                                                                                           |
| **Developer Portal**                | The developer documentation available at [Cash App Pay Partner API](/cash-app-pay-partner-api/guides/welcome).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Dispute**                         | Any dispute, complaint, or error alleged by a Customer regarding a Transaction or Goods.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **Goods**                           | The goods or services offered, sold, or distributed by a Merchant to a Customer that used Cash App Pay to make the Payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Liability**                       | Any and all damages (including lost profits or savings, indirect, consequential, special, exemplary, punitive, or incidental), penalties, fines, expenses and costs (including reasonable fees and expenses of legal and other advisers).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Linked Financial Instrument**     | The external bank account, debit card, credit card or other payment instrument, in each instance, linked to the Customer's Cash App Account, as permitted and enabled by Block.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Merchant**                        | A person or entity that accepts Cash App Pay in connection with Customers' Payment for Goods or to make donations. Merchants may enter into agreements with PSPs for the purpose of offering Cash App Pay to Customers, and must register, either directly or indirectly via their PSP, with Block and utilize the Cash App Pay API to process Cash App Pay Transactions for Customers. A Merchant may have one or more stores, websites, outlets, branches, or other commercial venues.                                                                                                                                                                                                                                       |
| **Merchant Use Policy (MUP)**       | The current Cash App Pay [Merchant Use Policy](/cash-app-pay-partner-api/guides/partnerships/merchant-use-policy), as amended by Block from time to time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **On File**                         | An arrangement between a Merchant and the Customer via the Merchant's Website(s), under which the Customer authorizes the use of the Cash App Pay for future Payments in one or both of the following forms:<br />• **Customer Initiated Transactions (CIT)** - A Transaction where the Customer is present on the Merchant's Website and actively initiates each Transaction without needing to log into their Cash App Account; and/or<br />• **Merchant Initiated Transactions (MIT)** - A Transaction where the Merchant initiates the Transaction without the Customer being present. MITs may include (A) one-time payments (such as capture amounts), or (B) automatic recurring payments on a fixed or variable basis. |
| **Payment**                         | A type of Transaction that uses Cash App Pay to send funds from a Customer to a Merchant to purchase Goods or to make donations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Payment Service Provider (PSP)**  | A person or entity that offers payment processing and settlement services to facilitate the purchase of, or payment of bills for, goods or services through clearance and settlement systems by agreements with other persons or entities, including Merchants. To offer Cash App Pay as a clearance and settlement system to Merchants, PSPs must enter into Cash App Pay-related service agreements with Block. Where a Merchant uses its integration with Afterpay to enable Cash App Pay via [Cash App Afterpay](/cash-app-afterpay/guides/welcome/getting-started), then Afterpay is the applicable Merchant's PSP.                                                                                                       |
| **Personal Information**            | Any information that identifies or can be used to identify, directly or indirectly, contact, or locate the individual person to whom such information pertains, and any other information subject to or governed by Applicable Data Protection Laws.<br /><br />Personal Information includes, without limitation, unique identifiers such as names, physical addresses, CashTags, photographs, government issued identification numbers, date of birth, place of birth, phone numbers, IP addresses, email addresses, and /or any other content containing Personal Information made available to Merchants in connection with the provision of Cash App Pay.                                                                 |
| **Personnel**                       | Employees, including employees of affiliates, subcontractors, and agents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Program Rules (Rules)**           | These Cash App Pay Program Rules which, along with other applicable documents and agreements, govern the use of the Cash App Pay API and the offering of Cash App Pay to Customers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Refund**                          | A type of Transaction that uses Cash App Pay to send funds from a Merchant to a Customer to refund an earlier corresponding Payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Taxes**                           | Include any and all present or future taxes, charges, fees, levies, or other assessments, including, without limitation, income, telecommunications, value-added, goods and services tax or similar taxes, gross receipts, excise, real or personal property, sales, withholding, social security, occupation, use, severance, environmental, license, net worth, payroll, employment, franchise, transfer and recording taxes, fees and charges, imposed by any domestic or foreign taxing authority.                                                                                                                                                                                                                         |
| **Transaction**                     | Money movement initiated via or processed through Cash App Pay.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Unauthorized Payment**            | Fraudulent or otherwise unauthorized Payment that: (1) arises from theft or unauthorized use of a Customer's Cash App Account or financial information related to Customer's credit card, debit card, external banking account or other user credentials, (2) occurs in an environment hosted by Block, and (3) Merchant reasonably believed the Payment was authorized and not fraudulent.                                                                                                                                                                                                                                                                                                                                    |
| **Website**                         | Website, mobile and web application.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Use of Cash App Pay

Use of Cash App Pay (CAP) is entirely at Block's discretion. Block may impose limits or conditions on the use of CAP by any Merchant, Payment Service Provider (PSP), or other person, or discontinue the service at any time for any reason without notice.

CAP may only be used for purposes expressly authorized by Block. CAP may be used only to facilitate Transactions using Cash App in accordance with these Program Rules (Rules) and the Cash App Pay Merchant Use Policy (MUP). Merchants must not initiate, accept payment for, or otherwise engage in unlawful or illegal Transactions. Merchants must not violate the Rules or do anything to cause anyone else to violate these Rules. Merchants will comply with and will ensure that their Personnel comply with the Rules and will be responsible for any breach of the Rules by their Personnel.

These Rules govern Merchants' use of CAP and the Cash App Pay API (CAP API). Merchants may enter into agreements with PSPs for the purpose of offering CAP to Customers, and must register, either directly or indirectly via their PSP, with Block and utilize the CAP API to process Transactions for Customers. A Merchant may have one or more stores, Websites, outlets, branches, or other commercial venues. These Rules do not constitute a contract, promise, or agreement with any third party. A Merchant's right to use CAP may not be assigned or transferred without prior written consent from Block. Block may, in its sole discretion, disable Merchant's use of CAP at any time.

In relation to each Transaction, Merchant represents and warrants to Block that:

* Merchant does not know of or have any reason to suspect fraud or suspicious activity relating to the Transaction;
* The Transaction represents a bona fide sale by Merchant to the Customer in the ordinary course of Merchant's business;
* The purchase and Merchant's terms and conditions associated with the Transaction, as well as the Goods or donations involved in the Transaction, comply with Applicable Law;
* The Goods or donations duly comply and conform with all terms, conditions, and any warranties (express or implied) applicable to the Transaction;
* In relation to Goods that are goods: (a) the Customer has or will have title to the Goods listed and clear of all encumbrances, licenses, and claims; and (b) the Goods at the time they were delivered to the Customer were of a merchantable and acceptable quality;
* In relation to Goods that are services: (a) the Goods have been or will be provided with due care and skill; and (b) the Goods will be delivered within the agreed time frame or within a reasonable time frame if no time has been agreed for the provision of the Goods; and
* In relation to Transactions for donations, you will utilize donations received via CAP in a manner consistent with Merchant's terms and conditions and Applicable Law.

Merchants will not, will not attempt to, and will not permit anyone else to:
(1) copy, reproduce, alter, modify, create derivative works, publicly display, republish, upload, post, transmit, resell or replicate any Block Services, in whole or in part, or any other materials made available to a PSP or Merchant in connection with CAP;
(2) decompile, disassemble, reverse engineer or otherwise deconstruct any Block Services or related component; or
(3) bypass or circumvent any security features for any Block Services, or otherwise alter any Block Services, including any copyright, trademark or other proprietary right.

### Changes

Block may revise, amend, modify, or otherwise change these Rules in its sole discretion, at any time and for any reason. The most up-to-date version of the Rules will be available on the Developer Portal and/or Block's website. Merchants should review these Terms from time to time for updates and changes that may impact them.

Block will have sole discretion in the interpretation and enforcement of these Rules.

### Waivers

Block's failure to require strict adherence with any provision of these Rules on any occasion will not constitute a waiver of Block's right to require adherence with that or any other provisions of these Rules.

## Merchant Eligibility

### Overview

CAP is only available to Merchants located in the United States, and all Transactions must occur entirely within the United States.

Block reserves the right to inquire about and take any corrective action it deems appropriate if it believes or suspects that any Merchant or Transaction violates the MUP, these Rules, or is otherwise illegal or unsuitable, or to disable any Transaction or Merchant for any reason it deems prudent. Block may also report any illegal or abusive activity in accordance with Applicable Laws.

### New features

As Block introduces new features related to CAP, certain features may be available only in certain regions or only to certain types of Merchants. Any such restrictions will be listed in these Rules.

### Merchant registration

All PSPs will register each Merchant with Block through the CAP API prior to initiating a Payment. Merchants with multiple locations, that are part of a franchise or chain, or that otherwise require identification with a brand or another entity may be required to provide their PSP with additional details to facilitate registration.

### On File

Merchant may only enable use of On File with Block's prior authorization. Block may withdraw this authorization at any time in its sole discretion. Block may restrict or prohibit any type or sub-type of CIT or MIT in its sole discretion. Each use of On File must comply with the Customer's prior On File authorization, any limits set by Block, and all Applicable Laws. Merchant must provide Block with sufficient information (such as metadata) as Block requires from time to time to: (1) allow Block to determine if a Transaction is a CIT or MIT and (2) for MITs, show the Customer's authorization.

When a Customer authorizes use of On File for future Payments, Block will issue a token to Merchant to be stored against that Customer's account with Merchant. Merchant may only use the token to initiate transactions that are consistent with the Customer's authorization. Merchant may not use any token for a Customer who has cancelled their On File authorization. A Customer may cancel their authorization either directly with Block or through Merchant's Website(s) or terms. Merchant must promptly notify PSP and Block if a Customer cancels On File authorization or if Merchant cancels the Customer's On File authorization. Merchant must ensure that the Customer can easily cancel their On File authorization at any time, via a clearly accessible option on Merchant's Website(s) or in Merchant's checkout flow.

To the fullest extent permitted by law, Merchant agrees to promptly reimburse Block from and for all claims, liabilities, losses, damages, costs and expenses Block incurs directly or indirectly from, or in connection with, any actual or alleged data breach, system failure, or unauthorized access to or use of Merchant's On File system where the Customer has elected to save or store their Cash App Account details with Merchant.

### Compliance

By utilizing CAP, Merchants agree to comply with and will ensure that all of its Personnel comply with all Applicable Laws.

Merchants will maintain all necessary licenses, permits, approvals and registrations from all applicable state, local and federal regulatory and governmental authorities. Transactions must be lawful in all of the following jurisdictions: (1) where the Customer resides, (2) where Merchant resides, and (3) where the Transaction occurs.

#### Information Requests and Investigations

Block may request information from Merchants in order to investigate Disputes; to validate adherence to, or to investigate violations of, these Rules, the MUP or other agreements; to respond to requests from law enforcement, regulatory, or other governmental entities; and for other routine business needs. Merchants will, at any time requested by Block, provide information related to CAP activities or otherwise facilitate collection and transmission of the requested information to Block. Requests will be sent to the contact information provided by Merchant at the time of registration with CAP or as otherwise provided to Block. Merchant will promptly notify Block of updated contact information in the event of a change of relevant Personnel.

Merchants will respond to and comply with Block's requests within a commercially reasonable timeframe not to exceed 10 business days.

#### Termination of a Merchant as a Result of Compliance Concerns

If Block determines, in its sole discretion, that a Merchant is submitting Transactions that violate these Rules, the MUP, or any Applicable Laws, Block may decline any Transaction or series of Transactions, suspend Merchant's participation in CAP until Merchant resolves its violations, subject to a resolution that is sufficient in Block's sole discretion, and/or terminate or decline to allow a Merchant to participate in CAP. Block may, in its sole discretion, provide Merchant the opportunity to cure violations prior to suspending or terminating Merchant's participation in CAP.

## Payment Limits and Liability

### Limits

Block implements Customer, Transaction, and velocity limits at its discretion for risk and compliance purposes. These limits may affect a Merchant's ability to process Transactions or a Customer's ability to make a Payment using CAP. Block may change these limits at any time and in its sole discretion.

### Liability

Merchants are responsible to Block for any Transaction submitted to CAP whether or not the Customer returns the underlying Goods to Merchant.

Block will only be liable to a Merchant for lost or misdirected funds for Transactions, and only if the loss or misdirection is caused solely and directly by Block. In such a case, Block will be liable only up to the authorization amount of the lost or misdirected Payment. Block will not be liable for any indirect, incidental, consequential, special, punitive, or other damages, and Block will not be liable to any third parties as a result of any lost or misdirected Payment.

## Disputes and Disputed Payments

### Refunds

Merchant will disclose its return/cancellation policy on its Websites. Merchant's policies and agreements (including applicable return/cancellation policy, complaints policy, treating customers fairly policy, and information security policies) with Customers will comply with Applicable Laws. Merchant will consider any Customer's request for a Refund in good faith and in accordance with Merchant's policies and Applicable Laws. A Refund will not exceed the total amount of the applicable Transaction. Merchant will not accept cash or any other consideration from Customer in exchange for issuing a Refund. Merchant will not give cash refunds in connection with a Transaction unless required by Applicable Laws. Please see Cash App Pay's Technical Guide on Refunds for more information regarding Refunds.

### Merchant expectations

Merchants will make a good faith attempt to promptly resolve any issues associated with a Transaction and to minimize the number of Disputes. Merchants are expected to be a Customer's first point of contact for issues, grievances, and other Customer support issues related to a Transaction, except as otherwise provided in these Rules.

### Errors related to Transactions

Only Customers can file Disputes. If a Customer believes there is an error related to a Transactions or has questions regarding a Transaction, Customer may:

* For Payments originating from Customer's Linked Financial Instrument, Customer must either (1) contact their issuing financial institution, or (2) contact Block via the procedure set forth in the Cash App Terms of Service.
* For Payments originating from Customer's Cash App Balance, Customers must follow the procedure set forth in the Cash App Terms of Service.

### Dispute liability and review

#### Unauthorized Payments

Block will assume Liability on behalf of Merchants for all Unauthorized Payments.

Block may restrict, suspend, or terminate a Merchant's use of CAP if Block, in its sole discretion, suspects Merchant of enabling or otherwise failing to prevent Unauthorized Payments, and Block reserves all rights to seek recovery from Merchant in such cases. Merchant will provide all information as reasonably requested by Block to facilitate Block's investigation of potential Unauthorized Payments.

#### Disputes

Except as required by Applicable Law (including Block's obligations under the Electronic Funds Transfer Act and Regulation E), Merchant will be liable for any Dispute resolved in the Customer's favor where such Dispute did not arise from an Unauthorized Payment. Merchant will receive notice of these Disputes via their PSP and will have the opportunity to provide supporting evidence for rebuttal. Merchants will respond to and handle Disputes in accordance with Cash App Pay's Technical Guide on Disputes.

If Merchant, whether directly or indirectly via a PSP, provides evidence to contest a Dispute, the Dispute will be reviewed and adjudicated by either Block or the Customer's financial institution, depending on where the Dispute was filed.

All Dispute adjudication decisions are final and may not be appealed.

### Dispute and risk monitoring

Block monitors all Dispute activity and notifies PSPs when any Merchant to whom they provide CAP-related services has excessive Dispute volumes. Once a PSP is notified of and provides notice to Merchant of excessive Disputes, Merchants will work to reduce their Dispute activity, including promptly responding to customer inquiries and operating as Customer's first point of contact with respect to Disputes. Block may, in its sole discretion, restrict Merchant's ability to use CAP if Merchant fails to take appropriate steps to reduce Dispute activity.

Block reserves the right to impose additional requirements or penalties on Merchants that have excessive Dispute volumes, including, but not limited to, increased reserve requirements, additional fee downgrades, liability shifting for Unauthorized Payments, and/or otherwise limiting, restricting, suspending, or terminating a Merchant's access to CAP. Further, Block will monitor Transactions for suspicious behavior and fraud claims brought against Merchants.

## Use of Cash App Marks

Merchants shall use commercially reasonable efforts to treat CAP equally to any other payment methods offered at their points of sale and on their Websites. This includes equal or better logo placement and position within any point of sale or Website, as well as equal or better treatment in any payment flow, terms and conditions, marketing or advertising materials, or fee structure. Further, Merchants shall endeavor to not indicate a preference for any payment type over CAP.

Block grants Merchant a non-exclusive, non-transferable, revocable and royalty free license to use and reproduce the CAP Marks solely within the U.S. and solely in connection with Merchant's display of CAP on its Websites or in-store(s) (as applicable), and checkout page, and as permitted under these Rules and any other written directions Block may issue from time to time including any use guidelines. Merchants must immediately discontinue, modify or change the use or display of the CAP Marks whenever instructed by PSP or Block.

Merchant's use of CAP Marks must adhere to the CAP Brand Guidelines. Block is the exclusive owner of the "Block", "Cash App", "Cash App Pay", and the CAP Marks. Merchant will not use the CAP Marks to indicate endorsement or affiliation with Block or Cash App without Block's prior express written consent. Merchant will not use the CAP Marks in any way that dilutes the goodwill or reputation of Block or any of its affiliates, brands, or programs. All use of the CAP Marks will inure for the benefit of Block.

## Customer Support

Block will provide Customers with customer support for technical issues related to Payments made or attempted with CAP.

Merchants will provide Customers with customer support for all other issues, including, but not limited to, Customers' inquiries related to the Goods or donations.

If Merchants need to direct Customers to contact Block to resolve an issue, they can instruct Customers to reach Cash App customer support directly in Cash App or by calling +1(800) 969-1940.

## Fees, Taxes, and Incentives

### Fees and Taxes

#### Transaction fees

Merchants will pay a fee for each Transactions in accordance with the terms of the applicable service agreement between Merchant and the PSP or Block.

#### No surcharges

Unless required by Applicable Laws, Merchants may not charge Customers a surcharge, convenience fee, or any other fee, or otherwise increase the price of any Goods, for accepting CAP as a payment method.

#### Taxes

Merchants are responsible and liable, as required under Applicable Law, for determining and paying any and all Taxes required to be assessed, incurred, collected, paid, or withheld for their use of CAP. Merchants are also responsible and liable for:

* Determining whether Taxes apply to their sale of Goods, Payments received, donations received, and any other transactions arising from or out of their use of CAP; and
* Calculating, collecting, reporting or remitting any Taxes to the appropriate tax and revenue authorities. Block specifically disclaims any liability for such Taxes.

### Incentives

Block may (unilaterally or in partnership with Merchant) offer incentives for Customers to use CAP or otherwise market or promote the use of CAP. Such incentives, marketing activities, or promotions are offered at Block's discretion, are not guaranteed, and may be discontinued, suspended, or modified by Block at any time.

## Confidentiality and Privacy

By offering or using CAP, Merchant represents, warrants, and covenants that it is and will remain in compliance with all Applicable Data Protection Laws and will process all Personal Information in compliance with all Applicable Data Protection Laws. Where necessary, Merchant will provide any necessary disclosures and/or obtain any necessary consents to provide Personal Information to Block.

Merchant must ensure all Restricted Information is kept strictly confidential and used only in connection with Payments or as otherwise provided for in these Rules or permitted by Block. Merchants will, upon request from Block, return or destroy any Restricted Information in its possession or control. "Restricted Information" includes any of the following:

* Any information transmitted by Block to a PSP or Merchant in connection with any Transaction,
* Any Cash App Account or Customer's Personal Information provided by Block to a PSP or Merchant,
* Any other information subject to or governed by Applicable Data Protection Laws, and
* Any non-public information shared by Block during discussions or negotiations related to CAP including, without limitation, proprietary technical information regarding CAP; information regarding Cash App's customers or customer base; product roadmap, marketing plans and strategies, market research, and other market information; costs, fees, and other financial data; and any other data of a confidential or proprietary nature.

Further, unless required by Applicable Laws, Merchant may not disclose to any third party or use any Cash App Account or Customer Personal Information other than to complete a Transaction, to resolve a Transaction-related Dispute, to perform risk evaluation and fraud prevention, or to provide an enhanced customer experience by providing access to transaction histories, receipts, and notifications. Block may use Restricted Information or Transaction-related information it receives from a Merchant to process  Transactions and as otherwise permitted under the Cash App Privacy Notice.

If Merchant is served with a court order, subpoena, civil investigative demand, or similar legal process compelling disclosure of Customer Personal Information, Merchant will promptly notify Block (and in any event within 48 hours)  and cooperate in good faith with Block in the event Block opposes disclosure. Merchant will limit the scope of such disclosure to what is strictly required by Applicable Laws.

Cash App Customer Personal Information and Cash App Account data is the proprietary information of Block. Block and Merchant are not providing or making available any Personal Information to the other for any consideration, and any such provision of Personal Information to the other shall not constitute a "sale" of Personal Information under any Applicable Data Protection Laws.

## Information Security

Block requires all Merchants interacting with CAP data to follow best practices for securing financial and Customer Personal Information data. This includes, but is not limited to:

* Implementing multi-factor authentication and role-based access controls and granting Personnel the least privilege necessary for job function
* Reviewing access controls periodically and disabling Personnel access upon departure
* Encrypting all data transmitted with the CAP API in transit
* Encrypting all data received from the CAP API at rest
* Conducting routine security audits and penetration tests of systems interacting with CAP data and credentials
* Implementing logging for access to CAP data
* Installing software security patches and updates in a timely manner
* Securing access to CAP data and credentials
* Rotating certificates and API keys for interacting with the CAP API on a routine basis
* Implementing controls designed to prevent intrusion or unauthorized access to Merchant's systems and Personal Information, including virus protection software, firewalls, intrusion prevention technologies and other measures designed to ensure appropriate levels of access are restricted to authorized Personnel
* Personnel training and controls, such as communication of all applicable security policies and confidentiality obligations, background checks (as permitted by Applicable Data Protection Laws), user authentication, security awareness training, and disciplinary processes
* Written confidentiality agreements governing access to Restricted Information by Personnel
* Controls designed to ensure the physical safety and security of Merchant's facilities, including, without limitation, records of access

Detailed requirements for information security are available on the Developer Portal. Block may revise, amend, modify, or otherwise change information security requirements at any time and for any reason. Merchants should, either directly or indirectly via their PSP, implement these requirements as soon as possible when updated to ensure the safety of Cash App Customers' data and finances.

In the event a Merchant determines that there has been any actual or suspected Data Security Breach, Merchant shall, without undue delay (and in any event within 48 hours), notify Block (via email to [breachnotifications@block.xyz](mailto:breachnotifications@block.xyz) , which may be updated from time to time) of the actual or suspected Data Security Breach. Merchant shall promptly initiate an investigation into the circumstances surrounding such Data Security Breach and shall reasonably cooperate with Block in remedying and addressing any such Data Security Breach.

## Enforcement

### General Enforcement

If Merchant is in breach of these Rules or any CAP-related agreements or terms, Block may take a number of actions at any time in its sole discretion. These include, but are not limited to:

* Assessing fee downgrades or other financial penalties
* Limiting Merchant's access to CAP
* Suspending or terminating Merchant's account or Merchant's access to and use of CAP
* Refusing to provide CAP services to Merchant in the future
* Reporting Merchant to the appropriate legal authorities
* Contacting Customers who have purchased Goods from a Merchant using CAP
* Other legal action

Except in circumstances described below where Block is permitted to terminate or suspend Merchant's CAP services immediately, prior to taking any action, Block will: (1) provide a Merchant with notice of the breach and, when practical, provide reasonable advance notice and an opportunity to cure, and (2) use reasonable efforts to attempt to resolve the matter in good faith. Merchant will use reasonable efforts to resolve any breach in good faith. Failure to cure the breach will result in termination of a Merchant's ability to use or offer CAP.

### Immediate Enforcement

Block may terminate or suspend a Merchant's use of CAP immediately (or for such other date as notified to Merchant) if:

* Merchant breaches these Program Rules or any CAP-related agreements and such breach is incapable of remedy;
* Merchant breaches the MUP;
* Merchant experiences a Data Security Breach;
* Block reasonably believes Merchant is engaging or has engaged in fraudulent activity or conduct; or
* Block is required to do so by any regulatory authority or in order to comply with Applicable Laws (including any change in Applicable Laws).

---

# Cash App Pay Integration Basics

## Overview

Cash App Pay integrations include both front-end and back-end components.

**Front end (client)**

The front end handles customer interactions and must be embedded in your app or website UI. This is done using the Pay Kit SDK, which provides the necessary UI elements and functionality for users to complete payments with Cash App.

**Back end (server)**

The back end handles your server-to-server communication with Cash App. It supports key operations like:

* Payment processing
* Merchant onboarding
* Credential rotation
* Settlements
* Dispute management

To support these, Cash App Pay provides the following APIs and tools:

* Network API
* Management API
* Batch Reporting
  * Settlements
  * Dispute Reporting

![Cash App Pay Integration Basics diagram](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/cap-build-basics.png)

## Front end

### Pay Kit

Pay Kit is a JavaScript SDK that lets you embed fully managed and branded UI elements into an app or website, allowing merchants to accept Cash App Pay online.

It adapts to the user's device:

* On desktop devices, it displays a QR code that customers can scan using Cash App (installed on their mobile device) to authenticate the payment request.

* On mobile devices (such as iOS and Android phones), customers are redirected from the merchant’s checkout experience to Cash App, where they authenticate the payment request. Then they're redirected back to the merchant’s site.

If a merchant’s integration needs more flexibility in how and when the customer request authorization flow is initiated, consider using Pay Kit’s [advanced controls](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/getting-started#advanced-controls) capabilities.

To learn more, see the [Pay Kit Developer Guide](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/getting-started).

## Back end

### Network API

The Network API is a server-side API that allows your back end to handle key Cash App Pay operations including:

* Payment processing
* Merchant registration
* Dispute handling

It's an entirely server-side API; it can't be called from a browser or point-of-sale (POS) device directly.

To learn more, see the [Network API documentation](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/network-api).

### Management API

The Management API provides tools to automate key aspects of your Cash App Pay integration, including:

* Secure credential rotation
* Managing webhook subscriptions
* Creating scoped API keys, which can be used in a microservices environment to give least-privileged access to services calling the Cash App Pay API

To learn more, see the [Management API documentation](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/management-api).

### Batch reporting

Cash App provides several different reports to help PSPs manage settlements and disputes with Cash App Pay. These reports are uploaded daily (regardless of payment activity) and should be processed on a regular basis.

#### Settlements

Cash App uploads several reconciliation reports daily to a PSP-hosted SFTP server. Process these files regularly to maintain correct settlement reporting.

To learn more, see [Settlements](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/settlement).

<Note>
  Cash App Pay provides a net settlement process, where refunds and disputes amounts are deducted from settlement amounts.
</Note>

#### Disputes

Cash App uploads a dispute report daily to a PSP-hosted SFTP server. Process these files regularly and use them with the Network API to manage customer disputes.

To learn more, see [Disputes Reports](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/introduction).

---

# API Integration Quickstart

We recommend that partners use the [Pay Kit SDK](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/pay-kit-benefits) to integrate with Cash App Pay.

<Note Title="Prerequisites">
  Before getting started, confirm with the Cash App Pay Partner Engineering team that the API-only approach is right for you. Make sure that you have access to:

  * API credentials and API access
  * Cash App Sandbox App

  We recommend reading the following pages:

  * [Cash App Pay Integration Basics](/cash-app-pay-partner-api/guides/technical-guides/cash-app-pay-integration-basics)
  * [Making Requests](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/making-requests)
  * [Sandbox App](/cash-app-pay-partner-api/guides/technical-guides/sandbox/sandbox-app)
</Note>

## Integrate with the Cash App Pay API

### Step 1: Create a Brand and Merchant

First, create a Brand and associate a Merchant with that brand.

1. Create a [Brand](/cash-app-pay-partner-api/api-reference/network-api/create-brand)
   ```curl
   curl --location 'https://sandbox.api.cash.app/network/v1/brands' \
   --header 'Authorization: {{api_creds}}' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'X-Region: PDX' \
   --data '{
     "brand": {
          "name": "Cash App",
          "reference_id": "external-id"
     },
     "idempotency_key": "224841f7-31be-4bc6-b1df-e102a8fa476f"
   }'
   ```

2. Create a [Merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant)

   ```curl
   curl --location 'https://sandbox.api.cash.app/network/v1/merchants' \
   --header 'Authorization: {{api_creds}}' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'X-Region: PDX' \
   --data '{
        "merchant": {
            "address": {
                  "address_line_1": "1 Market Street",
                  "locality": "San Francisco",
                  "country": "US",
                  "postal_code": "94105",
                  "administrative_district_level_1": "CA"
             },
             "name": "Cash App Pay on Market Street",
             "brand_id": "BRAND_bifwxjq70mfk06l9nr6q4q1f9",
             "country": "US",
            "currency": "USD",
             "category": "5500",
             "reference_id": "external-id"
        },
       "idempotency_key": "b12fa940-d07a-48c6-a08a-89511547661f"
    }'
   ```

<Note>
  These APIs are server-side between your website or application and Cash App Pay.
</Note>

### Step 2: Link a Customer to the Merchant, Brand, or Client

To link a Customer to the Merchant, Brand, or Client, do the following:

1. Create a customer request with one Channel and at least one Action.

   | Available Actions                                          | Available Channels                    |
   | ---------------------------------------------------------- | ------------------------------------- |
   | One Time Payment <br /> On File Payment <br />Link Account | IN\_APP <br />ONLINE <br /> IN PERSON |

   <Note>
     See the list of supported actions and channels [here](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request). You can have many actions but only one channel.
   </Note>

2. Save the Request ID and the URL from the `auth_flow_triggers` object in the response.
   <Note>
     When you call `create customer request`, a customer request is returned to you with `auth_flow_triggers` populated. This gives you access to URLs including the QR Code URL, Mobile URL, and Desktop URL.
   </Note>

3. Listen for updates to the customer request.

4. When the request enters the `approved` state, stop polling.

5. Save the Grant IDs listed in the `grants` array to [create a payment](#step-3-create-a-payment) later.

   <Note>
     To test the customer request, you can use the Sandbox App or Sandbox Web to scan and approve the request. See more at [Sandbox App](/cash-app-pay-partner-api/guides/technical-guides/sandbox/sandbox-app) and [Developer Sandbox](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox).
   </Note>

#### Listen for updates to the customer request

You can listen for updates to the customer request in two ways:

* **Polling (recommended):** Call [retrieve customer request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request) repeatedly (ideally once per second or more frequently).
* **Webhooks:** Subscribe to the `customer_request.state.updated` event.

QR codes rotate every 30 seconds and expire every 60 seconds, so you must get the latest QR code. This will change based on how you listen for customer request updates:

* If you are using polling, set the image tag’s URL to the latest QR code that is returned after each polling response. Since you poll more frequently than QR codes rotate, you don’t need to keep track of the `refreshes_at` value.
* If using webhook, there is no webhook event for QR code rotation. Instead, you should fetch the latest customer request once the current timestamp is after the `refreshes_at` value. The auth flow triggers will contain the newest, valid QR code.

<Note>
  These APIs are client-side from the browser to Cash App.
</Note>

**Example - Create Customer Request**

```curl
curl --location 'https://sandbox.api.cash.app/customer-request/v1/requests' \
--header 'Authorization: Client {{client ID}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "request": {
         "actions": [
              {
                   "amount": 1234,
                   "currency": "USD",
                   "scope_id": "{{client_id || brand_id || merchant_id}}",
                   "type": "ONE_TIME_PAYMENT"


              }
         ],
         "reference_id": "external-id",
         "channel": "ONLINE"
    },
    "idempotency_key": "cd8b0b0a-0ffb-478e-ae8f-e31aef666a1a"
}'
```

**Example - Retrieve Customer Request**

```curl
curl --location --globoff 'https://sandbox.api.cash.app/customer-request/v1/requests/{{customer_request_id}}' \
--header 'Authorization: Client {{client_id}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### Step 3: Create a Payment

You can now create a payment using the Grant ID and Merchant ID from the previous steps using the [Create a payment request](/cash-app-pay-partner-api/api-reference/network-api/create-payment) endpoint. You can use void, capture, or refund actions depending on the state of the payment.

<Note>
  We use magic values in the amount field to determine outcomes for payments in the sandbox environment.  You can use any amount, but [these amounts](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox#magic-values) will result in specific outcomes.
</Note>

**Example - Create Payment**

```curl
curl --location 'https://sandbox.api.cash.app/network/v1/payments' \
--header 'Authorization: {{api_creds}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Region: PDX' \
--data '{
    "payment": {
         "capture": true,
         "amount": 1234,
         "currency": "USD",
         "merchant_id": "{{merchant_id}}",
         "grant_id": "{{grant_id}}",
         "reference_id": "external-id"
    },
    "idempotency_key": "2a77b3a5-9104-4587-9517-53ac5d968f25"
}'
```

## Notes

### Pay Kit SDK

Pay Kit is the name of the Cash App Pay SDK.  This SDK specifically handles linking a Customer to a Merchant and uses the [Customer Request API](../../reference/Customer-Request-API.v1.yaml) underneath.  Instead of using the SDK, you can call the APIs directly as described in the steps to integrate with the Cash App Pay API above. To know more about our SDK, see [Pay Kit](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/getting-started).

### Signatures

Cash App Pay Network API and Management API require that all requests be signed.  However, when using Sandbox, you can skip this by setting `x-signature` to the value `sandbox:skip-signature-check`. Use these [Magic Values](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox#magic-values) to control the behavior in Sandbox and to produce preset outcomes.

---

# Comparing Mobile/Web Environments

{/* internal:true */}

---

# Cash App Pay: Comparing Mobile/Web environments

See the following table to compare the capability of Cash App Pay in different web and mobile environments.

| Scenario / Environment      | Description                                                                                                                                                                                                                                                                             | Production \[Native App]                                                                                                                                                                                | Sandbox \[Native App]                                                                                                                                   | Sandbox \[Web App]                                                                                                                      |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| International Support       | Cash App is available in the United States and the United Kingdom. However, Cash App Pay is currently only supported in the United States.                                                                                                                                              | Only valid US Cash App accounts can take Cash App Pay payments in production.                                                                                                                           | The Sandbox web app can be used globally.                                                                                                               | The Sandbox web app can be used globally.                                                                                               |
| Requires Cash App Installed | Cash App must be downloaded on the customer's mobile device in order to authenticate a Cash App Pay payment.                                                                                                                                                                            | If Cash App is not installed, an interstitial page will be shown where the customer is prompted to install Cash App.                                                                                    | If the Sandbox native app is not installed, the Sandbox web app is used instead where the customer can approve or deny the grant flow in a web browser. | The Sandbox web app does not require an app to be downloaded; instead, the customer can approve or deny the grant flow in a web browser |
| Interstitial Page Shown     | An interstitial page is shown after the Cash App Pay button is clicked if Cash App is not installed or if there are issues deeplinking into Cash App.                                                                                                                                   | This interstitial page is currently only shown in production                                                                                                                                            | N/A - the interstitial page is not shown in Sandbox.                                                                                                    | N/A - the interstitial page is not shown in Sandbox.                                                                                    |
| Mobile Forward Redirect     | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. After the grant flow is approved or declined, the customer is either returned back to the original checkout context via either a forward redirect or a backward redirect. | In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead. | The Sandbox native app mirrors production functionality.                                                                                                | The Sandbox web app will always initiate a forward redirect.                                                                            |
| Mobile Backward Redirect    | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. After the grant flow is approved or declined, the customer is either returned back to the original checkout context via either a forward redirect or a backward redirect. | In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead. | The sandbox native app mirrors production functionality.                                                                                                | The Sandbox web app does not support backward redirects.                                                                                |
| Approve Grant Flow          | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. If the grant flow is approved, a grant is generated which can be used to authorize a payment.                                                                             | In production, Cash App will automatically approve or decline the payment request without requiring any user action.                                                                                    | In Sandbox, the customer is able to manually approve or decline the payment request.                                                                    | In Sandbox, the customer is able to manually approve or decline the payment request.                                                    |
| Decline Grant Flow          | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. If the grant flow is declined, a grant is NOT generated.                                                                                                                  | In production, Cash App will automatically approve or decline the payment request without requiring any user action.                                                                                    | In Sandbox, the customer is able to manually approve or decline the payment request.                                                                    | In sandbox, the customer is able to manually approve or decline the payment request.                                                    |

{/*

---

# Cash App Pay: Comparing Mobile/Web environments

We have created the following tables for you to compare the capability of Cash App Pay in different web and mobile environments.
## Cash App

This table describes the behavior of Cash App Pay, in our mobile application Cash App, based on different use cases:

|Use case|Description|
| ----------- | -------- |
| International Support      | Cash App is available in the United States and the United Kingdom. However, Cash App Pay is currently only supported in the United States. |
|Requires Cash App Installed | Cash App must be downloaded on the customer's mobile device to authenticate a Cash App Pay payment. | 
|Interstitial Page Shown | An interstitial page is shown after the Cash App Pay button is clicked if Cash App is not installed or if there are issues deeplinking into Cash App. |
|Mobile Forward Redirect | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. After the grant flow has been approved or declined, the customer is either returned back to the original checkout context via either a forward redirect or a backward redirect. |
|Mobile Backward Redirect | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. After the grant flow has been approved or declined, the customer is either returned back to the original checkout context via either a forward redirect or a backward redirect. |
|Approve Grant Flow | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. If the grant flow is approved, a grant is generated which can be used to authorize a payment. | 
|Decline Grant Flow | When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. If the grant flow is declined, a grant is NOT generated. |

 

## Production [Native App]

This table describes the behavior of Cash App Pay within the Production environment based on different use cases: 
|Use case|Description|
| ----------- | -------- |
 | International Support  | Only valid US Cash App accounts can take Cash App Pay payments in production. |    
 | Requires Cash App Installed |If Cash App is not installed, an interstitial page will be shown where the customer is prompted to install Cash App. | 
 | Interstitial Page Shown |This interstitial page is currently only shown in production |
 | Mobile Forward Redirect |  In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead. |
 | Mobile Backward Redirect |  In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead. |
 | Approve Grant Flow |   In production, Cash App will automatically approve or decline the payment request without requiring any user action. | 
 | Decline Grant Flow |In production, Cash App will automatically approve or decline the payment request without requiring any user action. |




## Sandbox [Native App] 

This table describes the behavior of Cash App Pay within the Sandbox App mobile environment based on different use cases: 
|Use case|Description|
| ----------- | -------- |
 | International Support| The sandbox web app can be used globally.    |      
 | Requires Cash App Installed | If the sandbox native app is not installed, the sandbox web app is used instead where the customer can approve or deny the grant flow in a web browser. |
 | Interstitial Page Shown | N/A - the interstitial page is not shown in sandbox. | 
 | Mobile Forward Redirect |The sandbox native app mirrors production functionality. |
 | Mobile Backward Redirect | In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead. |  
 | Approve Grant Flow |In sandbox, the customer is able to manually approve or decline the payment request. | 
 | Decline Grant Flow |In sandbox, the customer is able to manually approve or decline the payment request. |




## Sandbox [Web App]  

This table describes the behavior of Cash App Pay within the Sandbox App web environment based on different use cases:

|Use case|Description|
| ----------- | -------- |
  | International Support   | The sandbox web app can be used globally.  |   
  | Requires Cash App Installed |The sandbox web app does not require an app to be downloaded; instead, the customer can approve or deny the grant flow in a web browser |
  | Interstitial Page Shown | N/A - the interstitial page is not shown in sandbox. |
  | Mobile Forward Redirect |The sandbox web app always initiates a foward redirect. |
  | Mobile Backward Redirect |he sandbox web app does not support backward redirects. | 
  | Approve Grant Flow |In sandbox, the customer is able to manually approve or decline the payment request. |
  | Decline Grant Flow |In sandbox, the customer is able to manually approve or decline the payment request. |

      
*/}

{/*
<table>
<tbody>
  <tr>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td colspan="2"></td>
    <td>International Support</td>
    <td>Requires Cash App Installed</td>
    <td>Interstitial Page Shown</td>
    <td>Mobile Forward Redirect</td>
    <td>Mobile Backward Redirect</td>
    <td>Approve Grant Flow</td>
    <td>Decline Grant Flow</td>
  </tr>
  <tr>
    <td colspan="2">DESCRIPTION</td>
    <td>Cash App is available in the United States and the United Kingdom. However, Cash App Pay is currently only supported in the United States. </td>
    <td>Cash App must be downloaded on the customer's mobile device in order to authenticate a Cash App Pay payment. </td>
    <td>An interstitial page is shown after the Cash App Pay button is clicked if Cash App is not installed or if there are issues deeplinking into Cash App.</td>
    <td>When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. After the grant flow has been approved or declined, the customer is either returned back to the original checkout context via either a forward redirect or a backward redirect.</td>
    <td>When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. After the grant flow has been approved or declined, the customer is either returned back to the original checkout context via either a forward redirect or a backward redirect.</td>
    <td>When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. If the grant flow is approved, a grant is generated which can be used to authorize a payment.</td>
    <td>When a customer clicks the Cash App Pay button, they are deeplinked into Cash App to complete the grant flow. If the grant flow is declined, a grant is NOT generated.</td>
  </tr>
  <tr>
    <td colspan="2">Production [Native App]</td>
    <td>Only valid US Cash App accounts can take Cash App Pay payments in production.</td>
    <td>If Cash App is not installed, an interstitial page will be shown where the customer is prompted to install Cash App.</td>
    <td>This interstitial page is currently only shown in production</td>
    <td>In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead.</td>
    <td>In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead.</td>
    <td>In production, Cash App will automatically approve or decline the payment request without requiring any user action.</td>
    <td>In production, Cash App will automatically approve or decline the payment request without requiring any user action.</td>
  </tr>
  <tr>
    <td colspan="2">Sandbox [Native App]</td>
    <td>The sandbox web app can be used globally.</td>
    <td>If the sandbox native app is not installed, the sandbox web app is used instead where the customer can approve or deny the grant flow in a web browser.</td>
    <td>N/A - the interstitial page is not shown in sandbox.</td>
    <td>The sandbox native app mirrors production functionality.</td>
    <td>In production, Cash App will attempt to backward redirect back to the original checkout context. In the scenario where this fails or for non-standard workflows, a forward redirect will occur instead.</td>
    <td>In sandbox, the customer is able to manually approve or decline the payment request.</td>
    <td>In sandbox, the customer is able to manually approve or decline the payment request.</td>
  </tr>
  <tr>
    <td colspan="2">Sandbox [Web App]</td>
    <td>The sandbox web app can be used globally.</td>
    <td>The sandbox web app does not require an app to be downloaded; instead, the customer can approve or deny the grant flow in a web browser</td>
    <td>N/A - the interstitial page is not shown in sandbox.</td>
    <td>The sandbox web app always initiates a foward redirect.</td>
    <td>The sandbox web app does not support backward redirects.</td>
    <td>In sandbox, the customer is able to manually approve or decline the payment request.</td>
    <td>In sandbox, the customer is able to manually approve or decline the payment request.</td>
  </tr>
</tbody>
</table>
*/}

---

# Brands and Merchants

## Relevant Terms

* **Client:** The developer that is making API calls to the Cash App Pay API. A client can create and update brands and merchants as needed.
* **Brand:** A Customer-facing business entity that aggregates related merchants within Cash App. Related merchants under a single business entity are aggregated into a Brand within Cash App. Customers will see their transactions grouped by brand within Cash App.
* **Merchant:** A business that a Customer can transact with. This could be an e-commerce store, a physical brick and mortar store, etc.

## Brand and Merchant Hierarchy

Brands have a one-to-many relationship with merchants. The Brand should always reflect the Customer-facing brand entity and not the corporate umbrella entity. For example, Block has several business units including Square, Cash App, Afterpay, Tidal. Separate Brands must be created for each of these business units instead of one Brand for “Block”.

> **Example:** Good Pour Coffee is a Brand and the Good Poor Coffee Shop at 1 Market St. is a Merchant under the Good Pour Coffee Brand.

When a customer request is created, it can be scoped to either the Client, Brand, or Merchant depending on the Customer request payment action. For example:

* **One-Time Payment:** Client, Brand, Merchant
* **On-File Payment:** Client, Brand

The value that is passed along has implications on what is presented to the Customer during the grant approval process and after the transaction is completed, within the Customer’s Cash App activities page.

The table below shows the different values passed and what is presented to the Customer during Grant approval:

| Value passed | What is presented to the Customer during Grant approval                                                                                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client**   | <ul><li>Client name and icon will be displayed during the customer linking process</li> <li>A valid grant scoped to a given client can be used to process a payment for any merchant associated with said client</li> </ul>           |
| **Brand**    | <ul><li>Brand name and icon will be displayed during the customer linking process</li> <li> A valid grant scoped to a given client can be used to process a payment for any merchant associated with said brand</li> </ul>            |
| **Merchant** | <ul><li>Brand name and icon associated with the merchant will be displayed during the customer linking process.</li> <li>A valid grant scoped to a given merchant can only be used to process a payment with said merchant</li> </ul> |

### Example

The “Cash by Cash App” brand icon and name are displayed to the customer during the customer linking desktop flow.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/scan-to-pay.png" alt="Scan to Pay" />

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/icon-and-brand.png" alt="Icon and Brand example" />

## Best Practices

* Brands and merchants should be created asynchronously from the customer request flow. This will minimize unnecessary API calls when the customer is utilizing Cash App Pay.
* Brands and merchants should be created with associated reference IDs.
* Brand and merchant data should be kept up to date with relevant brand and merchant data.

---

# Security Requirements

## Encryption

* All Cash App Pay data stored must be encrypted at rest.
* All Cash App Pay data must be encrypted during transit.
* All communications to the Cash App Pay API must use HTTPS and TLS 1.2+.
* All communications with the Network API and Management API must provide HMAC signatures in the `X-Signature` header.

## Credentials

* API keys must be rotated automatically every 30 days.
* API keys should be scoped to the least amount of access needed to process requests. For example, if a service only needs the ability to respond to disputes, you don't need to give it permission to register new merchants.

## Refreshing QR Codes

For security reasons, the QR codes expire periodically. If this happens, a new code will be generated automatically. This is called a **Refresh**.

![QR-code-refresh.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/QR-code-refresh.png)

![QR-code.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/QR-code.png)

---

# Optimizing Performance with Request Chaining

If you send multiple consecutive API requests, consider using request chaining to improve performance. Request chaining allows you to combine multiple requests into a single API call. Since all requests stay within Cash App's infrastructure, it significantly reduces roundtrip latency.

<Note>
  In internal test, chaining 3 requests—create brand, create merchant, and create customer —reduced latency by 50–70%. Actual performance gains may vary, depending on your infrastructure and the number of requests chained.
</Note>

Example usage:

* Create Brand > Create Merchant > Create Customer Request
* Upsert Brand > Upsert Merchant > Create Payment
* Retrieve Fee Plan > Upsert Merchant
* Create API Key > Update Webhook Endpoint

<Note>
  For example code snippets and implementation details, see the request chaining [API page](/cash-app-pay-partner-api/api-reference/management-api/create-request-chain).
</Note>

## Request chaining errors

### What happens if there's an error making a request?

It depends on where the error occurred, for example:

* If the error happened at the requested endpoint, such as while creating a brand, then request chaining will stop executing subsequent requests. It will return the error in the list of responses and all subsequent requests will be marked as `not started`.
* If the error happened in the request chaining logic, such as accessing a previous response's value, then it will return a validation error with a status code `400`.

---

# Introduction to Cash App Pay APIs

The Cash App Pay developer product is composed of three REST APIs and a Javascript SDK:

* **Customer Request API:** Used to get permission from customers to perform actions on their accounts (like collecting a payment)
* **Network API:** Registers merchants and processes payments using grants
* **Management API:** Controls API keys and webhooks
* **Pay Kit (JS SDK):** Wraps the Customer Request API and provides prebuilt UI components to add Cash App Pay to websites

As a developer, you'll use all of these API suites to build a complete Cash App Pay integration.

## Payment processing workflow

Most Cash App Pay workflows follow a simple pattern: create a customer request, get it approved by the customer to generate a grant, then use the grant to create a payment.

![payment-processing-workflow.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/payment-processing-workflow.png)

1. **Initiate a customer request**
   * Use Pay Kit in the browser to create a customer request.
   * Define the actions you want to perform (e.g. "charge \$5 for a coffee")

2. **Present the approval user experience**
   * When a customer request is created, the API returns an approval URL, which allows customers to approve or decline the request.
   * The URL opens in a web browser or on a Cash App mobile client. It's represented through a QR code or a navigation button.
   * Pay Kit automatically selects and renders the optimal user experience according to Cash App brand guidelines.

3. **Customer approves the request**
   * The approval generates grants, which represent the customer's permission to perform the actions listed in the customer request.

4. **Front end receives grants**
   * Pay Kit detects that the customer request is approved and returns the grants to the webpage's JavaScript.
   * The webpage sends the grant information to the server to process the payment.

5. **Back end processes payment**
   * On the server, the grant ID is sent to the Network API [Create Payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment) endpoint along with the payment amount, currency, and merchant ID.
   * The Network API consumes the grant and charges the customer for the given amount.

6. **Settlement**
   * The payment settles later that day. Funds are delivered to the developer to distribute to the merchant.

---

# Making Requests

The Cash App Pay API follows standard, RESTful JSON API conventions. All communication must be over `HTTPS` using TLS 1.2 or above.

We don't provide any server-side SDKs, so you'll need to write your own code to communicate with the API.

## Sample request

The following cURL request demonstrates how to form a valid request to the Cash App Pay API, including all required headers:

```json http
{
  "method": "post",
  "url": "https://sandbox.api.cash.app/network/v1/brands",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Client TEST_CLIENT_ID TEST_API_KEY_ID",
    "Content-Type": "application/json",
    "X-Region": "SEA",
    "X-Signature": "sandbox:skip-signature-check"
  },
  "body": {
    "brand": {
        "name": "My Brand"
    },
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"
  }
}
```

## Required headers

All requests to the Cash App Pay API require these headers:

* `Authorization`: This [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) is used to authenticate your API client with the Cash App Pay API
* `Accept`: This [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) ensures that the API client and Cash App Pay API are communicating using the same MIME type in the response payload

**For requests with payloads:**

* `Content-Type`: This [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) ensures that the API client and Cash App Pay API are communicating using the same MIME type in the request payload

**For the Network API only:**

* `X-Region`: This custom header helps the Cash App Pay API optimize latencies and data storage by routing requests closest to where you and your customers are

<Note>
   All other headers are ignored by the Cash App Pay API. We don't use the 

  `Accept`

   header because the only response content type is 

  `application/json`

  . 
</Note>

### Accept

All endpoints provided by the Cash App Pay API return `application/json` content. All requests sent to the API should specify this type in the `Accept` header.

**Example**

```
Accept: application/json
```

### Authorization

All endpoints require an `Authorization` header. However, what is sent in the header varies based on the API being called:

* The **Network API** and **Management API** require a client ID and API key, formatted as `Client <Client ID> <API Key ID>`.
  * The client ID is considered public information. The API key is secret and must be well-secured. API keys will automatically expire 30 days after they are created.
* The **Customer Request API** requires a client ID, formatted as `Client <Client ID>`.
  * Since the Customer Request API can be called from customers' browsers or point of sale devices, it only requires the client ID.

<Error>Never share API keys with browsers or point of sale devices.</Error>
**Example- Network API**

```
Authorization: Client <Client ID> <API Key ID>
```

**Example- Customer Request API**

```
Authorization: Client <Client ID>
```

### Content-Type

There are two content types supported by the Cash App Pay API:

* `application/json`: This is used by the vast majority of endpoints. It specifies that the request contains a JSON payload (if a payload is provided). API clients should default to setting this content type on each request.
* `multipart/form-data`: File upload endpoints use this content type to break the request into 2 parts: a JSON payload with file metadata and a binary payload which contains the actual file. This is currently only used by the [create dispute evidence file](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file) endpoint.

**Example- Standard endpoints**

```
Content-Type: application/json
```

**Example- File upload endpoints**

```
Content-Type: multipart/form-data
```

### X-Region

To improve latencies for API clients and customers, Cash App Pay can run in multiple regions simultaneously. The `X-Region` header tells the Cash App Pay API which region the API client/consumers are closest to. It's required on all calls to the Network and Management APIs.

<Note Title="Note">
   Idempotency is scoped to a single region. If you make a request with the same idempotency key to two separate regions, you may create duplicate data. 
</Note>

**Example**

```text
X-Region: PDX
```

### X-Signature

To prevent payload tampering and keep plaintext secrets out of API requests, all requests to the Cash App API must be signed, with the signature passed in the `X-Signature` header.

When Cash App receives the request, a signature is calculated for the request and verified against the signature the API client provided. If they match, the request will complete successfully. If not, it fails.

`X-Signature` is required on all calls to the Network API and Management API.

<Note>
   When making requests in the sandbox, the magic signature value of 

  `sandbox:skip-signature-check`

   is always accepted in place of a valid signature. 
</Note>

Learn how to [sign requests](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/signing-requests) to start making API requests.

---

# Signing Requests

> To sign `multipart/form-data` requests, see the section [Signing Multipart Requests.](#signing-multipart-requests)

All requests to the Network and Management APIs must be *signed* and have a valid signature passed in the `X-Signature` header. To generate the signature:

1. Construct the following string: `{method}\n{path}\n{headers}\n{bodyDigest}`, where:

   * `{method}` is the HTTP method, in uppercase.

   * `{path}` is the remainder of the URL following the host, including the query string (if present).

   * `{headers}` is the concatenation of the following headers (if present) in the form `{lowercase(name)}:{strip(value)}\n`:

     * `Accept`
     * `Authorization`
     * `Content-Type`
     * `Host`

   * `{bodyDigest}` is the lowercased, hexadecimal representation of the SHA256 digest of the bytes of the request body (hashing an empty string if there is no body).

2. Create an HMAC-SHA256 cryptographic hash where the text to hash is the string you created in step 1, and the secret is the secret value associated with the API key being used to make the request.

3. Set the `X-Signature` header to `V1 {signature}` where:

   * `{signature}` is the signature obtained in step 2 in hexadecimal, lowercased.

   > Instead of computing a real signature in Sandbox, you can use a [magic header value](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox): `X-Signature: sandbox:skip-signature-check`

4. Set an `Authorization` header of `Client {CLIENT_ID} {KEY_ID}` where:

   * `{CLIENT_ID}` is the client ID value obtained from Cash App
   * `{KEY_ID}` is the Cash App identifier for the API key used to generate the signature in step 2

```javascript
// Example request
// curl --request GET \
//      --url 'https://sandbox.api.cash.app/network/v1/payments?limit=50' \
//      --header 'accept:application/json' \
//      --header 'Authorization:Client {CLIENT_ID} {CLIENT_KEY}' \
//      --header 'content-type:application/json' \
//      --header 'host:sandbox.api.cash.app' \
//      --header 'X-Region: PDX' \
//      --header 'X-Signature: {X-Signature}'

//Loading the crypto module in node.js
let crypto = require('crypto');

// API Credentials
let client_id = '';
let api_key = '';
let api_secret = '';
let path = '/network/v1/payments?limit=50';
let host = 'sandbox.api.cash.app';

// STEP 1: construct the following string: {method}\n{path}\n{headers}\n{bodyDigest}
let method = 'GET';
let headers = 'accept:application/json' + '\nauthorization:Client ' + client_id + ' ' + api_key + '\ncontent-type:application/json' + '\nhost:' + host;
let body_digest = crypto.createHash('sha256').update('').digest('hex');
let raw_signature = method + '\n' + path + '\n' + headers + '\n' + body_digest

// STEP 2: create an HMAC-SHA256 crypto hash with API secret.
let hashed_signature = crypto.createHmac('sha256', api_secret).update(raw_signature).digest('hex');

// STEP 3: X-Signature header should be set to the following schema "V1 {signature}
let final_signature = 'V1 ' + hashed_signature;

//Printing the output on the console
console.log("X-Signature: " + final_signature);
```

> **Webhook signatures:** Webhook deliveries also contain an `X-Signature` header that is computed using the same process. This allows webhooks delivered by Cash App to be validated by computing the signature from the request payload and verifying that it matches the `X-Signature` header

---

# Signing Multipart Requests

To sign requests using the `multipart/form-data` content type, use this modified signing algorithm:

1. Construct the following string: `{method}\n{path}\n{headers}\n{bodyDigest}`, where:
   * `{method}` is the HTTP method, in uppercase.

   * `{path}` is the remainder of the URL following the host, including the query string (if present).

   * `{headers}` is the concatenation of the following headers (if present) in the form `{lowercase(name)}:{strip(value)}\n`:

     * `Accept`
     * `Authorization`
     * `Content-Type` (this should be `multipart/form-data` with no other parameters)
     * `Host`

   * `{bodyDigest}` is the lowercased, hexadecimal representation of the SHA256 digest of the bytes of the `request` object specified in the request body.

2. Create an HMAC-SHA256 cryptographic hash where the text to hash is the string you created in step 1, and the secret is the secret value associated with the API key being used to make the request.

3. Append a `text/plain` object named `signature` to the request body, containing the value `V1 {signature}` where `{signature}` is the value obtained in step 2 in hexademical and lowercased.

   > This signature will take precedence over any `X-Signature` header present in the request.

   > Instead of computing a real signature in Sandbox, you can use a [magic value](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox#magic-values): `sandbox:skip-signature-check`

---

# API Versioning

## API Versions

### Customer Request API

Current Version: **`v1`**

**API Versions:**

* **`v1`**
  * Status: Active; under continued development
  * Support Window (subject to change): January 1st, 2022 - March 1st, 2027
  * Accepting new developers

### Network API

Current Version: **`v1`**

**API Versions:**

* **`v1`**
  * Status: Active; under continued development
  * Support Window (subject to change): January 1st, 2022 - March 1st, 2027
  * Accepting new developers

* **`v0`**
  * Status: Deprecated
  * Support Window: August 1st, 2020 - December 31st, 2022
  * Not accepting new developers

### Management API

Current Version: **`v1`**

**API Versions:**

* **`v1`**
  * Status: Active; under continued development
  * Support Window (subject to change): January 1st, 2022 - March 1st, 2027
  * Accepting new developers

***

## Version Statuses

API Versions can be in one of 5 statuses:

* **Active**: The API is actively serving traffic and receiving new features from patch updates
* **In development**: The API is currently being built and is not available for public use
* **Maintenance**: The API is actively serving traffic, but is no longer receiving new features
* **Deprecated**: The API is within a year of being retired, and should no longer be adopted by new integrations. Existing integrations should plan to migrate to a newer API version.
* **Retired**: The API is no longer serving traffic.

Support window refers to the period in which the API will serve traffic.

## How to select an API version

The Cash App Pay API uses **path-based versioning**. Every API call is required to specify a version, which can be done by providing it in the URL path  after the name of the API suite you're calling:

**Network API**

```
Format: https://api.cash.app/network/v<Major.Minor>
Example: https://api.cash.app/network/v1
```

**Customer Request API**

```
Format: https://api.cash.app/customer-request/v<Major.Minor>
Example: https://api.cash.app/customer-request/v1
```

Each API suite is versioned independently.

## Types of changes between versions

There are 3 types of changes Cash App Pay makes to the API, some of which are versioned:

* Major (breaking) changes
* Minor changes
* Patches

### Major Version Changes

Major versions introduce new features or functionality in a non-backwards-compatible way, and / or remove existing functionality. They require modifying business logic in the integration to adopt.

Examples of changes in major version updates:

* Removing an endpoint
* Removing a field from a request or response
* Making a response field optional that was previously required
* Removing a country code from the list of supported countries

### Minor Version Changes

Minor versions introduce new features or functionality that are generally backwards-compatible, but may require modifying a small amount of business logic in the integration.

Examples of changes in minor version updates:

* Adding a new country code to the list of supported countries
* Adding a new state to a resource with a state machine (for example, a new payment state)

### Patches

Patches introduce new features or functionality that are guaranteed to be 100% backwards-compatible with existing integrations. Patches are **non-versioned**, and will routinely be applied by the Cash App Pay engineering team.

Examples of patches:

* Adding a new "notes" field to payments that allows an API client to add details about a payment that are shown in the Cash App mobile application
* Adding a new endpoint for listing customer requests

---

# Regions and Localization

## What are regions used for

The Cash App Pay API requires regions in requests to:

* Improve availability by allowing Cash App Pay to run in multiple, independent regions simultaneously without sacrificing consistency
* Reduce latencies by storing data closer to the geographic location of the API client
* Comply with data sovereignty regulations
* Support strongly consistent, idempotent processing of requests in independent regions; see [Idempotency](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/idempotency) for more details

## How do I know which region to use?"

The region you pick should be the one closest to where your own services are hosted. For example, if you are hosting your services in the [AWS US West (Oregon) region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions) (also known as `us-west-2`), you would want to pick `PDX` as the region code, since Portland is the closest city to Oregon.

> **Data sovereignty laws overrule physical proximity:** If you are serving customers in a country with strict data sovereignty laws, you must pass a region code that is associated with a city within that country. This allows Cash App Pay to comply with data sovereignty regulations before any data is associated with a customer, which is important for privacy laws.",

## How do I set the region on a request

Set the `X-Region` header to one of the supported values to set the region for the request.

**X-Region Header**

```
X-Region: PDX
```

## Supported region / IATA airport codes

The following table contains the list of all region / IATA airport codes that will be accepted by the Cash App Pay API in the `X-Region` header. Other codes will be rejected with an `INVALID REGION` error (See  [General Validation Errors](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#general-validation-errors) `INVALID REGION` error code)

| Code | City                                       |
| ---- | ------------------------------------------ |
| ABJ  | Abidjan, Ivory Coast                       |
| ABQ  | Albuquerque, United States                 |
| ACC  | Accra, Ghana                               |
| ACE  | Arrecife, Spain                            |
| ADB  | Izmir, Turkey                              |
| ADD  | Addis Ababa, Ethiopia                      |
| ADL  | Adelaide, Australia                        |
| AEP  | Buenos Aires, Argentina                    |
| AER  | Sochi, Russia                              |
| AGP  | Malaga, Spain                              |
| AIT  | Aitutaki, Cook Islands                     |
| AKL  | Auckland, New Zealand                      |
| ALC  | Alicante, Spain                            |
| ALG  | Algiers, Algeria                           |
| AMD  | Ahmedabad, India                           |
| AMS  | Amsterdam, Netherlands                     |
| ANC  | Anchorage, United States                   |
| APW  | Faleolo, Samoa                             |
| ARN  | Stockholm, Sweden                          |
| ASU  | Asuncion, Paraguay                         |
| ATH  | Athens, Greece                             |
| ATL  | Atlanta, United States                     |
| AUH  | Abu Dhabi, United Arab Emirates            |
| AUS  | Austin, United States                      |
| AYT  | Antalya, Turkey                            |
| BCN  | Barcelona, Spain                           |
| BDL  | Windsor Locks, United States               |
| BEG  | Belgrade, Serbia                           |
| BGO  | Bergen, Norway                             |
| BGY  | Bergamo, Italy                             |
| BHX  | Birmingham, United Kingdom                 |
| BKI  | Kota Kinabalu, Malaysia                    |
| BKK  | Bangkok, Thailand                          |
| BLQ  | Bologna, Italy                             |
| BLR  | Bangalore, India                           |
| BNA  | Nashville, United States                   |
| BNE  | Brisbane, Australia                        |
| BOD  | Bordeaux, France                           |
| BOG  | Bogota, Colombia                           |
| BOM  | Mumbai, India                              |
| BOS  | Boston, United States                      |
| BPN  | Balkipapan, Indonesia                      |
| BRS  | Bristol, United Kingdom                    |
| BRU  | Brussels, Belgium                          |
| BSB  | Brasilia, Brazil                           |
| BSL  | Mulhouse, France                           |
| BTH  | Batam, Indonesia                           |
| BUD  | Budapest, Hungary                          |
| BUS  | Batumi, Georgia                            |
| BWI  | Baltimore, United States                   |
| BZE  | Belize City, Belize                        |
| CAI  | Cairo, Egypt                               |
| CAN  | Guangzhou, China                           |
| CBR  | Canberra, Australia                        |
| CCU  | Kolkata, India                             |
| CDG  | Paris, France                              |
| CEB  | Cebu, Phillippines                         |
| CGK  | Jakarta, Indonesia                         |
| CGN  | Cologne, Germany                           |
| CGO  | Zhengzhou, China                           |
| CGQ  | Changchun, China                           |
| CHC  | Christchurch, New Zealand                  |
| CJU  | Cheju, South Korea                         |
| CKG  | Chongqing, China                           |
| CLE  | Cleveland, United States                   |
| CLT  | Charlotte, United States                   |
| CMH  | Colombus, United States                    |
| CMN  | Casablanca, Morocco                        |
| CNF  | Belo Horizonte, Brazil                     |
| CNS  | Cairns, Australia                          |
| CNX  | Chiang Mai, Thailand                       |
| COK  | Kochi, India                               |
| COO  | Cotonou, Benin                             |
| CPH  | Copenhagen, Denmark                        |
| CPT  | Cape Town, South Africa                    |
| CRL  | Charleroi, Belgium                         |
| CSX  | Changcha, China                            |
| CTA  | Catania, Italy                             |
| CTS  | Sapporo, Japan                             |
| CTU  | Chengdu, China                             |
| CUN  | Cancun, Mexico                             |
| CVG  | Cincinnati, United States                  |
| CWB  | Curitiba, Brazil                           |
| DAD  | Danang, Vietnam                            |
| DAR  | Dar Es Salaam, Tanzania                    |
| DEL  | Delhi, India                               |
| DEN  | Denver, United States                      |
| DFW  | Dallas, United States                      |
| DKR  | Dakar, Senegal                             |
| DLA  | Doulala, Cameroon                          |
| DLC  | Dalian, China                              |
| DOH  | Doha, Qatar                                |
| DPS  | Denpasar, Indonesia                        |
| DTW  | Detroit, United States                     |
| DUB  | Dublin, Ireland                            |
| DUS  | Dusseldorf, Germany                        |
| DXB  | Dubai, United Arab Emirates                |
| EBB  | Entebbe, Uganda                            |
| ECN  | Nicosia, Cyprus                            |
| EDI  | Edinburgh, United Kingdom                  |
| ESB  | Ankara, Turkey                             |
| FAO  | Faro, Portugal                             |
| FCO  | Rome, Italy                                |
| FIH  | Kinshasa, Democratic Republic of the Congo |
| FOC  | Fuzhou, China                              |
| FRA  | Frankfurt, Germany                         |
| FUE  | Fuerteventura, Spain                       |
| FUK  | Fukuoka, Japan                             |
| GDL  | Guadalajara, Mexico                        |
| GIG  | Rio de Janeiro, Brazil                     |
| GLA  | Glasgow, United Kingdom                    |
| GOA  | Goa, India                                 |
| GOT  | Gothenborg, Sweden                         |
| GRU  | São Paulo, Brazil                          |
| GUA  | Guatemala City, Guatemala                  |
| GVA  | Geneva, Switzerland                        |
| HAK  | Haikou, China                              |
| HAM  | Hamburg, Germany                           |
| HAN  | Hanoi, Vietnam                             |
| HAV  | Havana, Cuba                               |
| HEL  | Helsinki, Finland                          |
| HER  | Heraklion, Greece                          |
| HET  | Hohhot, China                              |
| HFE  | Hefei, China                               |
| HGH  | Hangzhou, China                            |
| HKG  | Hong Kong, China                           |
| HKT  | Phuket, Thailand                           |
| HND  | Tokyo, Japan                               |
| HNL  | Honolulu, United States                    |
| HOU  | Houston, United States                     |
| HRB  | Harbin, China                              |
| HRE  | Harare, Zimbabwe                           |
| HYD  | Hyderabad, India                           |
| IAD  | Washington D.C., United States             |
| IAH  | Houston, United States                     |
| IBZ  | Ibiza, Spain                               |
| ICN  | Seoul, Korea                               |
| INC  | Yinchuan, China                            |
| IND  | Indianapolis, United States                |
| IST  | Istanbul, Turkey                           |
| JED  | Jeddah, Saudi Arabia                       |
| JFK  | New York, United States                    |
| JJN  | Quanzhou, China                            |
| JNB  | Johannesburg, South Africa                 |
| JOG  | Yogyakarta, Indonesia                      |
| KBP  | Kiev, Ukraine                              |
| KEF  | Keflavik, Iceland                          |
| KHH  | Kaohsiung, Taiwan                          |
| KHN  | Nanchang, China                            |
| KIX  | Osaka, Japan                               |
| KMG  | Kunming, China                             |
| KNO  | Medan, Indonesia                           |
| KRT  | Khartoum, Sudan                            |
| KUL  | Kuala Lumpur, Malaysia                     |
| KWE  | Guiyang, China                             |
| KWL  | Guilin, China                              |
| LAD  | Luanda, Angola                             |
| LAS  | Las Vegas, United States                   |
| LAX  | Los Angeles, United States                 |
| LED  | St. Petersburg, Russia                     |
| LHR  | London, United Kingdom                     |
| LHW  | Lanzhou, China                             |
| LIM  | Lima, Peru                                 |
| LIN  | Milano, Italy                              |
| LIS  | Lisbon, Portugal                           |
| LJG  | Lijiang, China                             |
| LOS  | Lagos, Nigeria                             |
| LPA  | Gran Canaria, Spain                        |
| LUX  | Luxembourg, Luxembourg                     |
| LYS  | Lyon, France                               |
| MAA  | Chennai, India                             |
| MAD  | Madrid, Spain                              |
| MAN  | Manchester, United Kingdom                 |
| MCI  | Kansas City, United States                 |
| MCO  | Orlando, United States                     |
| MED  | Madinah, Saudi Arabia                      |
| MEL  | Melbourne, Australia                       |
| MEX  | Mexico City, Mexico                        |
| MGA  | Managua, Nicaragua                         |
| MHD  | Mashhad, Iran                              |
| MIA  | Miami, United States                       |
| MLA  | Malta, Malta                               |
| MNL  | Manila, Philippines                        |
| MRS  | Marseille, France                          |
| MRU  | Plaisance, Mauritius                       |
| MSP  | Minneapolis, United States                 |
| MSQ  | Minsk, Belarus                             |
| MSY  | New Orleans, United States                 |
| MTY  | Monterrey, Mexico                          |
| MUC  | Munich, Germany                            |
| MUN  | Maturin, Venezuela                         |
| MXP  | Milano, Italy                              |
| NAN  | Nandi, Fiji                                |
| NAP  | Naples, Italy                              |
| NBO  | Nairobi, Kenya                             |
| NCE  | Nice, France                               |
| NGB  | Ninbo, China                               |
| NGO  | Nagoya, Japan                              |
| NIM  | Niamey, Niger                              |
| NKG  | Nanjing, China                             |
| NNG  | Nanning, China                             |
| OAK  | Oakland, United States                     |
| OKA  | Okinawa, Japan                             |
| OOL  | Coolangatta, Australia                     |
| OPO  | Porto, Portugal                            |
| ORD  | Chicago, United States                     |
| OSL  | Oslo, Norway                               |
| OTP  | Bucharest, Romania                         |
| OUA  | Ouagadougou, Burkina Faso                  |
| PDX  | Portland, United States                    |
| PEK  | Beijing, China                             |
| PEN  | Penang, Malaysia                           |
| PER  | Perth, Australia                           |
| PHL  | Philadelphia, United States                |
| PHX  | Phoenix, United States                     |
| PIT  | Pittsburgh, United States                  |
| PNQ  | Pune, India                                |
| POA  | Porto Alegre, Brazil                       |
| POM  | Port Moresby, Papua New Guinea             |
| PPG  | Pago Pago, American Samoa                  |
| PRG  | Prague, Czech Republic                     |
| PTY  | Panama City, Panama                        |
| PUS  | Busan, South Korea                         |
| PVG  | Shanghai, China                            |
| RDU  | Raleigh, United States                     |
| REC  | Recife, Brazil                             |
| RGN  | Yangon, Burma                              |
| RIX  | Riga, Latvia                               |
| RUH  | Riyadh, Saudi Arabia                       |
| RUR  | Rurutu, French Polynesia                   |
| SAL  | San Salvador, El Salvador                  |
| SAN  | San Diego, United States                   |
| SAP  | San Pedro Sula, Honduras                   |
| SAT  | San Antonio, United States                 |
| SCL  | Santiago, Chile                            |
| SEA  | Seattle, United States                     |
| SFO  | San Francisco, United States               |
| SGN  | Ho Chi Minh City, Vietnam                  |
| SHE  | Shenyang, China                            |
| SHU  | Sharjah, United Arab Emirates              |
| SID  | Amilcar Cabral, Cape Verde                 |
| SIN  | Singapore                                  |
| SJC  | San Jose, United States                    |
| SJJ  | Saajevo, Bosnia & Herzegovina              |
| SJO  | San Jose, Costa Rica                       |
| SJW  | Shijiazhuang, China                        |
| SKG  | Thessaloniki, Greece                       |
| SLC  | Salt Lake City, United States              |
| SMF  | Sacramento, United States                  |
| SNA  | Santa Ana, United States                   |
| SOF  | Sofia, Bulgaria                            |
| SSA  | Salvador, Brazil                           |
| STL  | St. Louis, United States                   |
| STR  | Stuttgart, Germany                         |
| SUB  | Surabaya, Indonesia                        |
| SVO  | Moscow, Russia                             |
| SYD  | Sydney, Australia                          |
| SYX  | Sanya, China                               |
| SZX  | Shenzhen, China                            |
| TAO  | Qingdao, China                             |
| TBU  | Tongatapu, Tonga                           |
| TFS  | Tenerife, Spain                            |
| THR  | Tehran, Iran                               |
| TIJ  | Tijuana, Mexico                            |
| TLS  | Toulouse, France                           |
| TLV  | Tel-Aviv, Israel                           |
| TNA  | Jinan, China                               |
| TNR  | Antananarivo, Madagascar                   |
| TPA  | Tampa, United States                       |
| TPE  | Taipei, Taiwan                             |
| TRW  | Tarawa, Kiribati                           |
| TSN  | Tianjin, China                             |
| TUN  | Tunis, Tunisia                             |
| TXL  | Berlin, Germany                            |
| TYN  | Taiyuan, China                             |
| UPG  | Ujung Pandang, Indonesia                   |
| URC  | Urumqi, China                              |
| VCE  | Venice, Italy                              |
| VCP  | Campinas, Brazil                           |
| VIE  | Vienna, Austria                            |
| VLC  | Valencia, Spain                            |
| WAW  | Warsaw, Poland                             |
| WLG  | Wellington, New Zealand                    |
| WLS  | Wallis, Wallis & Fortuna                   |
| WNZ  | Wenzhou, China                             |
| WUH  | Wuhan, China                               |
| WUX  | Wuxi, China                                |
| XIY  | Xi'an, China                               |
| XMN  | Xiamen, China                              |
| YEG  | Edmonton, Canada                           |
| YHZ  | Halifax, Canada                            |
| YNT  | Yantai, China                              |
| YOW  | Ottawa, Canada                             |
| YUL  | Montreal, Canada                           |
| YVR  | Vancouver, Canada                          |
| YWG  | Winnipeg, Canada                           |
| YYC  | Calgary, Canada                            |
| YYZ  | Toronto, Canada                            |
| ZAG  | Zagreb, Croatia                            |
| ZRH  | Zurich, Switzerland                        |
| ZUH  | Zhuhai, China                              |

---

# Using API Keys

Cash App Pay APIs are primarily authenticated using API keys. These keys are provisioned and rotated using automation. These keys can be used for different actions. Therefore, we recommend provisioning multiple API Keys with the lowest privilege required.

## First Instantiation

1. Using your provided client ID and client secret in the `Authorization` header for the request, [create an API key](/cash-app-pay-partner-api/api-reference/management-api/create-api-key) with `API_KEYS_READ` and `API_KEYS_WRITE` scopes
2. Using the newly created API Key (not your client secret), you should [create](/cash-app-pay-partner-api/api-reference/management-api/create-api-key) a new set of API keys with the payment/operational scopes required (`PAYMENTS_READ`, `PAYMENTS_WRITE`, etc.)
3. You can now make requests using the API key created in **Step 2** above.

## Before expiration

We strongly recommend rotating keys several days before they expire to provide a buffer for unexpected problems.

Use a key with the `API_KEYS_WRITE` scope to generate new keys for each key created in **Step 1** and **Step 2** under **First Instantiation**.

## FAQ

**Q: How long do API keys remain valid?**

**A:** API keys expire after 30 days. The `expires_at` field contains the exact expiration date.

**Q: Does generating a new key cause the previous one to expire?**

**A:** No, keys only expire based on their `expires_at` timestamp.

**Q: What are some of the technical notes about key rotations?**

**A:** These are some of the technical notes or "gotchas" that you must be aware of while using our API keys:

* Our webhooks are signed using whichever API Key is associated with the webhook configuration when the webhook event is delivered. Using your private key, you can decrypt the webhook’s signature and validate that its contents match the actual data, ensuring that the payload hasn’t been tampered with and that it authentically came from Cash App Pay. See more about [Signing Requests](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/signing-requests).<br />Therefore, your API key and webhook logic should be able to handle instances where a webhook is fired using key\_1, but you receive the webhook after the API Key has been rotated to key\_2.
* Depending on your infrastructure, you should also consider cases where—if you have multiple instances of your app—API Keys don’t propagate to all instances synchronously.
* You should also build in appropriate retry and escalation policies if API Keys fail to rotate in production to avoid service outages.

---

# Error Handling

## What do errors look like in the Cash App Pay API?

The Cash App Pay API follows a standard pattern for representing errors in API responses:

1. A non HTTP 2XX response code is returned (typically a 4XX or 5XX)
2. An array of errors is present under the `errors` field at the top level of the response (see the sample below)

### Example Error

```json
{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "MISSING_REQUIRED_FIELD",
      "detail": "Missing required parameter 'amount'",
      "field": "amount"
    }
  ]
}
```

## How should I check for errors in my code?

The simplest way to check for errors is to see if a non HTTP 2XX code was returned. If a non HTTP 2XX code was returned, you can then log the `errors` array to get more information about what went wrong.

PII (personally identifiable information) will never be present in the errors, so you don't need to worry about scrubbing them before logging.

## What errors do I need to handle as part of my integration?"

There are different types of errors that can be returned by the API, each of which should be handled differently.

### Errors you need to handle

* [**Payment processing errors**](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#payment-processing-errors) indicate that a payment or refund was declined. **You need to handle these errors in your integration.** Dealing with declined payments or deactivated customers is something your integration will need to do on a regular basis, and should elegantly handle these failures.

* [**Grant errors**](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#grant-errors) can occur when a customer revokes an on-file payment grant in Cash App, causing on-file payments to fail. **You need to handle these errors in your integration.** This is considered a common use case, and your integration should elegantly handle it.

* [**API errors**](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#api-errors) indicate that something is wrong with the Cash App Pay APIs themselves. An integration should consider itself degraded if these errors are encountered, and temporarily remove the Cash App Pay functionality from their websites and / or point of sale devices.

### Errors that indicate bugs in the integration

* [**Authentication errors**](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#authentication-errors) indicate that the integration has faulty authorization headers set, or isn't managing API key rotation properly. This should be caught at development time, and should never be present in a production integration. Integrations shouldn't expect to handle these errors.

* [**Invalid request errors**](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#validation-errors) indicate that the integration is sending invalid requests to the API. These errors should be caught at development time, and should never be present in a production integration. Integrations shouldn't expect to handle these errors.

* [**Rate limit errors**](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#rate-limit-errors) indicate that the integration is making requests too quickly to the Cash App Pay API. You should either lower the number of requests you're making to the API, or reach out to Cash App Pay support to get the limits raised. Note that payment processing and merchant registration endpoints are never rate limited - only reporting and management endpoints are.

---

# Error Code Reference

A comprehensive list of all the errors that can be thrown by the Cash App Pay API

## Overview

This reference describes every error that can occur within the Cash App Pay APIs, why it happened, and how to resolve it.

### Error Schema

Errors in the Cash App Pay API are returned in every endpoint with the same format: an array of error objects at the top level of the response. Here's an example:

**Example Error**

```
{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "MISSING_REQUIRED_FIELD",
      "detail": "Missing required parameter 'amount'",
      "field": "amount"
    }
  ]
}
```

Each error has the following fields:

| Field Name                      | Description                                                                                                                                                                                                                                                                                                                                  |                                                                     |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| category <br />string, required | Contains a high-level grouping of the error that occurred from the following values: <br />  - API\_ERROR <br />  - AUTHENTICATION\_ERROR <br /> - BRAND\_ERROR <br /> - DISPUTE\_ERROR  <br /> - GRANT\_ERROR  <br /> - MERCHANT\_ERROR <br /> - INVALID\_REQUEST\_ERROR  <br /> - PAYMENT\_PROCESSING\_ERROR   <br /> - RATE\_LIMIT\_ERROR | This field is versioned, and can safely be used for error handling. |
| code  <br />string, required    | Contains a stable error code from the list of codes on this page. <br />This field is versioned, and can safely be used for error handling.                                                                                                                                                                                                  |                                                                     |
| detail <br /> string, optional  | Describes the error in human-readable US English, with description of why it occurred and how to resolve it.   <br />This field is not structured or versioned, and may change at any time. Do not rely on the detail field for error handling; instead, rely on the code field.                                                             |                                                                     |
| field   <br />string, optional  | Contains the name of the field that caused and / or is related to this error, in [JSON dot notation format](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics#dot_notation).                                                                                                                                          |                                                                     |

### Retry Behaviors

All requests to the Cash App Pay API are idempotent, but you should only retry requests in certain cases. There are 3 types of retry behaviors documented below:

| Retry Type                 | Description                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Retryable                  | The error can be resolved by retrying the request as-is, possibly after waiting a short period of time. No changes to the request are necessary to retry and possibly get a different response. <br /><br />  This retry behavior is typically associated with rate limiting, internal server errors, or waiting for automated state transitions.                |
| Retryable with New Payload | The error can be resolved by retrying the request, but requires changing the request payload first. This retry behavior is typically associated with validation failures, where the API client isn't sending valid data.                                                                                                                                         |
| Permanent (Do Not Retry)   | The error cannot be resolved by retrying the request in any capacity. This behavior is typically associated with payment or refund declines, where the API client sent a valid request, but Cash App Pay rejected it. <br /> <br /> The API client will need to create a new request and grant to proceed instead of attempting to modify/reuse an existing one. |

<Note>
  For more information about handling errors in your code, see [error handling](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-handling).
</Note>

## Authentication Errors

The following errors occur *before* a request is processed by the Cash App API, during authentication and authorization. They are typically related to issues with the credentials passed to the API.

All validation errors have a category of `AUTHENTICATION_ERROR`.

| Error Code                                                                                                                                   | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="UNAUTHORIZED" href="#UNAUTHORIZED">**UNAUTHORIZED**</a> <br />HTTP 401   <br />Retryable with New Payload                             | The Cash App Pay API could not authenticate your request. This is typically due to:  <br /> - Using sandbox credentials in production (or vice versa) <br />- Using an invalid syntax for the authorization header   <br />- Using a mismatched client ID / API key pair <br /> <br />To resolve this issue, double-check that you've set your credentials in the authorization header properly for the endpoint you're calling.  <br /><br /> If you can't resolve it with your existing credentials, reach out to Cash App Pay support and we'll issue new credentials for you or look into why your requests aren't being authenticated properly. |
| <a id="ACCESS_TOKEN_REVOKED" href="#ACCESS_TOKEN_REVOKED">**ACCESS\_TOKEN\_REVOKED**</a>  <br /> HTTP 401  <br /> Retryable with New Payload | The client ID and API key provided were both valid and in the correct format, but the API key was revoked and may no longer be used to make calls.  <br /><br /> Refresh your API credentials to get a new API key and resolve this issue.                                                                                                                                                                                                                                                                                                                                                                                                           |
| <a id="ACCESS_TOKEN_EXPIRED" href="#ACCESS_TOKEN_EXPIRED">**ACCESS\_TOKEN\_EXPIRED**</a>    <br />HTTP 401  <br />Retryable with New Payload | The client ID and API key provided were both valid and in the correct format, but the API key has expired and may no longer be used to make calls.   <br /> Refresh your API credentials to get a new API key and resolve this issue.                                                                                                                                                                                                                                                                                                                                                                                                                |
| <a id="CLIENT_DISABLED" href="#CLIENT_DISABLED">**CLIENT\_DISABLED**</a>     <br /> HTTP 401  <br />Retryable                                | The client ID and API key provided were both valid and in the correct format, but the API client has been disabled by Cash App Pay and is not allowed to make API calls.     <br /> Reach out to Cash App Pay support if your API client has been improperly disabled, and they can get it re-enabled for you.                                                                                                                                                                                                                                                                                                                                       |
| <a id="FORBIDDEN" href="#FORBIDDEN">**FORBIDDEN**</a> <br /> HTTP 403 <br />Retryable with New Payload                                       | The access token and client ID provided were valid, but don't have access to the requested resource. Typically, this is caused by passing a resource ID that isn't valid or managed by this API client.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| <a id="INSUFFICIENT_SCOPES" href="#INSUFFICIENT_SCOPES">**INSUFFICIENT\_SCOPES**</a>  <br /> HTTP 403 <br /> Retryable with New Payload      | The client ID and API key provided were both valid and in the correct format, and the client itself has access to the requested resource. However, this specific access token does not have the required permissions to perform the current action on the resource. <br /><br />Use a different API key that has permissions for the endpoint you're calling to resolve this.                                                                                                                                                                                                                                                                        |

## Validation Errors

The Cash App Pay API validates all requests sent by API clients to ensure they match the documented schemas. If a request does not match the schema, a validation error will be returned.

All validation errors have a category of `INVALID_REQUEST_ERROR`.

<Warning title="Do not automatically retry validation errors">
  Validation errors will continue to return the same error code if the API client continues to make requests with the same payload. Retrying the request will not change the response
</Warning>

### General Validation Errors

The following errors may occur when the request is unable to be parsed due to invalid data being passed by the API client. These errors may occur on any request or field, regardless of the field's data type.

| Error Code                                                                                                                                          | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| EXPECTED\_JSON\_BODY   <br />HTTP 400 <br /> Retryable with New Payload                                                                             | The API client sent a request without a JSON payload to an endpoint that requires a payload, or the JSON provided in the payload was unparseable. <br /> <br />The API client should make sure that it is passing a valid JSON payload to the endpoint. <br /> <br />If you're not sure if your JSON is valid, try using an online JSON validation tool (there are many of them) to give you feedback.                                                                                                                           |
| MISSING\_REQUIRED\_PARAMETER   <br /> HTTP 400      <br /> Retryable                                                                                | The API client did not provide a required query or body parameter.<br /> <br />Refer to the `field` parameter on the error object to see which field should have been present, but was not found in the payload.                                                                                                                                                                                                                                                                                                                 |
| <a id="CONFLICTING_PARAMETERS" href="#CONFLICTING_PARAMETERS">**CONFLICTING\_PARAMETERS**</a>  <br /> HTTP 400 <br /> Retryable with New Payload    | The API client sent a request payload that repeats parameters in the body that would overwrite each other (i.e., duplicate keys).       <br /><br /> Refer to the `field` parameter on the error object to see which field had duplicates in the request payload.                                                                                                                                                                                                                                                                |
| <a id="UNKNOWN_QUERY_PARAMETER" href="#UNKNOWN_QUERY_PARAMETER">**UNKNOWN\_QUERY\_PARAMETER**</a> <br /> HTTP 400 <br /> Retryable with New Payload | The API client sent a query parameter that does not exist in this version of the API.  <br /><br /> Refer to the `field` parameter on the error object to see which field could not be recognized.  <br /><br />The Cash App Pay API returns errors for unknown fields to prevent API clients from setting a field that isn't supported in a given API version, which could cause data integrity issues.                                                                                                                         |
| <a id="UNKNOWN_BODY_PARAMETER" href="#UNKNOWN_BODY_PARAMETER">**UNKNOWN\_BODY\_PARAMETER**</a>    <br /> HTTP 400  <br />Retryable with New Payload | The API client sent a field in the request payload that does not exist in this version of the API.  <br /><br /> Refer to the `field` parameter on the error object to see which field could not be recognized.    <br /><br /> The Cash App Pay API returns errors for unknown fields to prevent API clients from setting a field that isn't supported in a given API version, which could cause data integrity issues.                                                                                                         |
| <a id="INVALID_CONTENT_TYPE" href="#INVALID_CONTENT_TYPE">**INVALID\_CONTENT\_TYPE**</a>  <br />HTTP 400  <br /> Retryable with New Payload         | The API client specified a Content-Type header on the request that is not supported by the endpoint. <br /> Two content types are used in the API: <br /> - application/json, the standard type for all endpoints except file uploads <br /> - multipart/form-data, for file uploads only; part of the request is a JSON payload, the other part is a binary representation of the file.      <br /><br />The API client must set one of these content types as the header on each request. No other content types are accepted. |
| <a id="MISSING_REGION" href="#MISSING_REGION">**MISSING\_REGION**</a>   <br /> HTTP 400  <br /> Retryable with New Payload                          | The API client did not set the required X-Region header. <br /><br /> The API uses regions to provide lower latencies for API clients, enforce idempotency, and respect data sovereignty. Regions (in the form of an IATA airport code) must be specified on each request using the X-Region header. See [Regions and Localization](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/regions-and-localization)   for more information.                                                                |
| <a id="INVALID_REGION" href="#INVALID_REGION">**INVALID\_REGION**</a>     <br /> HTTP 400 <br /> Retryable with New Payload                         | The API client set the required X-Region header to an unrecognized code. <br /><br /> The API client should change the X-Region header value to a valid code from the [Regions and Localization](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/regions-and-localization) page.                                                                                                                                                                                                                     |
| <a id="FEATURE_DISABLED" href="#FEATURE_DISABLED">**FEATURE\_DISABLED**</a> <br /> HTTP 400 <br /> Retryable with New Payload                       | The API client set a field that requires a feature which is currently disabled for them. <br /><br /> The API client should stop using the functionality described in the message of the error and reach out to Cash App Pay support to request access if necessary.                                                                                                                                                                                                                                                             |

### String Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts string values.

| Error Code                                                                                                                             | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="EXPECTED_STRING" href="#EXPECTED_STRING">**EXPECTED\_STRING**</a><br />HTTP 400<br />Retryable with New Payload                 | The API client passed a non-string value to a field that only accepts strings.<br /><br />Refer to the `field` parameter on the error object to see which field should have been a string, but received a different data type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| <a id="VALUE_TOO_LONG" href="#VALUE_TOO_LONG">**VALUE\_TOO\_LONG**</a><br />HTTP 400<br />Retryable with New Payload                   | The API client passed a string with too many characters to a field that has a maximum character length requirement.<br /><br />Refer to the `field` parameter on the error object to see which field had too many characters. The API documentation for that field should include the maximum character length it requires.                                                                                                                                                                                                                                                                                                                                                                                                          |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| VALUE\_TOO\_SHORT<br />HTTP 400<br />Retryable with New Payload                                                                        | The API client passed a string with too few characters to a field that has a minimum character length requirement.<br /><br />Refer to the `field` parameter on the error object to see which field had too few characters. The API documentation for that field should include the minimum character length it requires.                                                                                                                                                                                                                                                                                                                                                                                                            |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| <a id="VALUE_EMPTY" href="#VALUE_EMPTY">**VALUE\_EMPTY**</a><br />HTTP 400<br />Retryable with New Payload                             | The API client passed an empty string or whitespace-only string to a field that requires a non-empty value.<br /><br />Refer to the `field` parameter on the error object to see which field failed validation. The API client must pass at least one non-whitespace character to pass this validation.                                                                                                                                                                                                                                                                                                                                                                                                                              | INVALID\_ENUM\_VALUE<br />HTTP 400<br />Retryable with New Payload | The API client passed a value which was not in the set of allowed values for the given field.<br /><br />Refer to the \`field parameter on the error object to see which field failed validation. The API documentation for that field should include a list of valid values for the API client to provide to the field. | VALUE\_REGEX\_MISMATCH<br />HTTP 400<br />Retryable with New Payload | The API client passed a value which did not match a regular expression the API used to validate the value.<br /><br />Refer to the `field` parameter on the error object to see which field failed validation. The API documentation for that field should include a sample of the regular expression used to validate it. |
| <a id="INVALID_TIME" href="#INVALID_TIME">**INVALID\_TIME**</a><br />HTTP 400<br />Retryable with New Payload                          | The API client passed a value which could not be parsed by the server to a field accepting RFC-3339 formatted dates and / or timestamps, or the passed timestamp was not using UTC.<br /><br />Refer to the `field` parameter on the error object to see which field has an invalid date or timestamp. The API requires all time-related values to comply with [RFC-3339](https://datatracker.ietf.org/doc/html/rfc3339), which is a more restrictive subset of the [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard:<br />- Dates are formatted as YYYY-MM-DD.<br />- Timestamps are formatted as YYYY-MM-DDTHH:MM:DDZ.<br />Note that all timestamps must be in UTC time, or they will fail validation. |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| INVALID\_EMAIL\_ADDRESS<br />HTTP 400<br />Retryable with New Payload                                                                  | The API client passed a value which could not be parsed by the server to a field accepting well-formatted email addresses.<br />Refer to the `field` parameter on the error object to see which field has an invalid email address. At a minimum, the API requires email addresses to contain at least one character followed by an @ sign and then at least one more character, i.e. a\@b.                                                                                                                                                                                                                                                                                                                                          |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| <a id="INVALID_PHONE_NUMBER" href="#INVALID_PHONE_NUMBER">**INVALID\_PHONE\_NUMBER**</a><br />HTTP 400<br />Retryable with New Payload | The API client passed a value which could not be parsed by the server to a `field` accepting well-formatted phone numbers.<br /><br />Refer to the `field` parameter on the error object to see which field has an invalid phone number. We recommend using [libphonenumber](https://github.com/google/libphonenumber) to validate phone numbers before passing them to the API.                                                                                                                                                                                                                                                                                                                                                     |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |
| INVALID\_URL<br />HTTP 400<br />Retryable with New Payload                                                                             | The API client passed a value which could not be parsed by the server to a field accepting well-formatted URL.<br />Refer to the `field` parameter on the error object to see which field has an invalid URL. At a minimum, the API requires URLs to start with http\:// or https\:// and contain a domain and / or IP address.                                                                                                                                                                                                                                                                                                                                                                                                      |                                                                    |                                                                                                                                                                                                                                                                                                                          |                                                                      |                                                                                                                                                                                                                                                                                                                            |

### Integer Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts integer values.

| Error Code                                                                                                                | Description and Resolution                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="EXPECTED_INTEGER" href="#EXPECTED_INTEGER">**EXPECTED\_INTEGER**</a><br />HTTP 400<br />Retryable with New Payload | The API client passed a non-integer value to a field that only accepts integers.<br />Refer to the `field` parameter on the error object to see which field should have been a integer, but received a different data type.        |
| <a id="VALUE_TOO_HIGH" href="#VALUE_TOO_HIGH">**VALUE\_TOO\_HIGH**</a><br />HTTP 400<br />Retryable with New Payload      | The API client passed a larger integer than allowed to an integer field.<br />Refer to the `field` parameter on the error object to see which integer field requires a smaller value, then retry the request with a valid integer. |
| <a id="VALUE_TOO_LOW" href="#VALUE_TOO_LOW">**VALUE\_TOO\_LOW**</a><br />HTTP 400<br />Retryable with New Payload         | The API client passed a smaller integer than allowed to an integer field.<br />Refer to the `field` parameter on the error object to see which integer field requires a larger value, then retry the request with a valid integer. |

### Boolean Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts boolean values.

| Error Code                                                                                                                | Description and Resolution                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="EXPECTED_BOOLEAN" href="#EXPECTED_BOOLEAN">**EXPECTED\_BOOLEAN**</a><br />HTTP 400<br />Retryable with New Payload | The API client passed a non-boolean value to a field that only accepts booleans.<br />Refer to the `field` parameter on the error object to see which field should have been a boolean, but received a different data type. |

### Array Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts array values.

| Error Code                                                                  | Description and Resolution                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **EXPECTED\_ARRAY**<br />HTTP 400<br />Retryable with New Payload           | The API client passed a non-array value to a field that only accepts arrays.<br /><br />Refer to the `field` parameter on the error object to see which field should have been an array, but received a different data type.                                                                                                |
| **ARRAY\_LENGTH\_TOO\_LONG**<br />HTTP 400<br />Retryable with New Payload  | The API client passed more than the minimum number of elements to an array field.<br /><br />Refer to the `field` parameter on the error object to see which array field requires fewer elements.                                                                                                                           |
| **ARRAY\_LENGTH\_TOO\_SHORT**<br />HTTP 400<br />Retryable with New Payload | The API client passed fewer than the minimum number of elements to an array field.<br /><br />Refer to the `field` parameter on the error object to see which array field requires additional elements.                                                                                                                     |
| **INVALID\_ARRAY\_TYPE**<br />HTTP 400<br />Retryable with New Payload      | The API client passed an array to an array field, which is valid, but the data type within the array did not match the expected data type.<br /><br />Refer to the `field` parameter on the error object to see which array field has an invalid data type, then use the detail field to see what the correct data type is. |

### Object Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts nested objects.

| Error Code                                                         | Description and Resolution                                                                                                                                                                                                      |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **EXPECTED\_OBJECT**<br />HTTP 400<br />Retryable with New Payload | The API client passed a non-object value to a field that only accepts objects.<br /><br />Refer to the `field` parameter on the error object to see which field should have been an object, but received a different data type. |

### Map Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts maps.

| Error Code                                                                | Description and Resolution                                                                                                                                             |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TOO\_FEW\_MAP\_ENTRIES**<br />HTTP 400<br />Retryable with New Payload  | The API client did not add enough keys to the map.<br /><br />Refer to the `field` parameter on the error object to see which field was not provided with enough keys. |
| **TOO\_MANY\_MAP\_ENTRIES**<br />HTTP 400<br />Retryable with New Payload | The API client added too many keys to the map.<br /><br />Refer to the `field` parameter on the error object to see which field has too many map keys.                 |

## Common Runtime Errors

The following error codes are re-used throughout the Cash App Pay API and handle common errors, such as missing resources, pagination problems, and idempotency key reuse.

All of the following errors have a category of `INVALID_REQUEST_ERROR`.

| Error Code                                                                   | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **NOT\_FOUND**<br /> HTTP 404 <br />Retryable with New Payload               | The API client requested a resource that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct ID in the request.<br /><br />Unless the ID parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request.                                                                                                                                                                                                       |
| **CONFLICT**<br />HTTP 409<br />Retryable                                    | The action to perform on the resource cannot be completed due to a conflict with the current state of the resource or its related resources.                                                                                                                                                                                                                                                                                                                                                                                                         |
| **INVALID\_CURSOR**<br />HTTP 400<br />Retryable with New Payload            | The API client provided a cursor to a paginated endpoint that could not be parsed by the API.The API client should ensure that it is passing the correct cursor in the request.<br /><br />If the API client can't identify a valid cursor to provide, it should restart pagination by passing a blank cursor in the request and getting a new, valid cursor from the response.<br /><br />Unless the cursor parameter is changed, the endpoint will continue to respond with an "invalid cursor" error and the client should not retry the request. |
| **IDEMPOTENCY\_KEY\_REUSED**<br />HTTP 400<br />Retryable with New Payload   | The idempotency key provided by the API client has already been used with a different request payload on this endpoint.<br /><br />The API client must retry the request with a different idempotency key.                                                                                                                                                                                                                                                                                                                                           |
| **INVALID\_STATE\_TRANSITION**<br />HTTP 400<br />Retryable with New Payload | The API client is attempting a change not allowed by the state machine for the resource.<br /><br />This error indicates that the API client is referring to stale data or has a bug in its business logic. The API client should not retry the request.                                                                                                                                                                                                                                                                                             |
| **CLIENT\_NOT\_FOUND**<br />HTTP 400<br />Retryable with New Payload         | The API client passed a client ID value in the request payload that did not match the API client's ID, OR no client could be found for the given client ID in the request payload.<br /><br />The API client must retry the request with a different (and valid) client ID.                                                                                                                                                                                                                                                                          |
| **IDEMPOTENCY\_PAYLOAD\_MISMATCH**<br />HTTP 400                             | A previous idempotency key was already used to perform an action on the given resource with the given payload. <br /><br />The action cannot be performed again with a new idempotency key.                                                                                                                                                                                                                                                                                                                                                          |

## Rate Limit Errors

The Cash App Pay API rate limits OLAP (online analytical processing) requests to guarantee that the Cash App Pay service stays fast and stable. These include operations such as:

* Listing payments for an API client by reference ID
* Retrieving a list of active grants approved by a given customer
* ...and any other "list" or "search" endpoints in the API

*Reach out to Cash App Pay support at any time to request rate limit increases on these endpoints, and we will be happy to adjust them for you.*

<Note title="Payment processing requests are never rate-limited">
  **OLTP** (online transaction processing) requests related to payment acceptance are **never** rate-limited. This includes, but is not limited to:

  * Creating, reading, voiding, and capturing individual Payments
  * Creating, reading, voiding, and capturing individual Refunds
  * Creating, upserting, reading, and updating individual Bbrands
  * Creating, upserting, reading, and updating individual Merchants
  * Creating, reading, and updating Customer Requests
  * Reading and revoking Individual Grants

  Refer to the API reference pages for any endpoint to see if it's rate limited.
</Note>

| Error Code                                     | Description and Resolution                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **RATE\_LIMITED**<br />HTTP 429<br />Retryable | The API client is making too many requests too quickly and should reduce the number of calls it's making to the API.<br /><br />Rate-limited requests are not checked for validity, so errors may be encountered when they are retried later on.<br /><br />The API client should retry the requests at a slower pace using exponential backoff. |

## Payment Processing Errors

The following error codes may occur in payment processing flows. In addition to these errors, [grant errors](#grant-errors) may occur during payment processing, while using grants to create a payment.

All payment processing errors have a category of `PAYMENT_PROCESSING_ERROR`.

| Error Code                                                                                                                                                                                               | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="MERCHANT_NOT_FOUND" href="#MERCHANT_NOT_FOUND">**MERCHANT\_NOT\_FOUND**</a><br />HTTP 400<br />Retryable with New Payload                                                                         | The API client provided a merchant ID in the request that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct merchant ID in the request.<br /><br />Unless the merchant ID parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request.                                                                                                                                                                                                                                                                                                             |
| <a id="PAYMENT_NOT_FOUND" href="#PAYMENT_NOT_FOUND">**PAYMENT\_NOT\_FOUND**</a><br />HTTP 400<br />Retryable with New Payload                                                                            | The API client provided a payment ID or idempotency key in the request that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct payment ID or idempotency key in the request.<br /><br />Unless the payment ID or idempotency key parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request.                                                                                                                                                                                                                                                       |
| <a id="REFUND_NOT_FOUND" href="#REFUND_NOT_FOUND">**REFUND\_NOT\_FOUND**</a><br />HTTP 400<br />Retryable with New Payload                                                                               | The API client provided a refund ID or idempotency key in the request that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct refund ID or idempotency key in the request.<br /><br />Unless the refund ID or idempotency key parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request.                                                                                                                                                                                                                                                          |
| <a id="CUSTOMER_DISABLED" href="#CUSTOMER_DISABLED">**CUSTOMER\_DISABLED**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                                               | The customer the API client is trying to take a payment or issue a refund for is deactivated in Cash App Pay and cannot send or receive funds. The payment or refund is declined.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.                                                                                                                                                                                                                                                                                                                                                 |
| <a id="MERCHANT_DISABLED" href="#MERCHANT_DISABLED">**MERCHANT\_DISABLED**</a><br />HTTP 400<br />Retryable                                                                                              | The merchant the API client is trying to take a payment or issue a refund for is deactivated in Cash App Pay and cannot send or receive funds. The payment or refund is declined.<br /><br />The API client should consider this a retryable decline. Retrying the request when a merchant has become active will change the response. Grants are not consumed by this decline.<br /><br />Merchants can be deactivated by Cash App or by the API client. API client-initiated deactivations can be reversed using the [UpdateMerchant](/cash-app-pay-partner-api/api-reference/network-api/update-merchant) endpoint. Cash App-initiated deactivations are permanent and cannot be reversed. |
| <a id="MERCHANT_PENDING" href="#MERCHANT_PENDING">**MERCHANT\_PENDING**</a><br />HTTP 400<br />Retryable                                                                                                 | The merchant the API client is trying to take a payment or issue a refund for is still being onboarded to Cash App Pay.<br /><br />The API client should consider this a retryable decline. Retrying the request once the merchant is active will change the response. Grants are not consumed by this decline.<br /><br />The API client must wait for the merchant to move from a status of PENDING to ACTIVE before using it to take payments or issue refunds. This generally happens within 15 minutes of merchant creation, but may take longer in rare cases.                                                                                                                          |
| <a id="PAYMENT_DECLINED_COMPLIANCE" href="#PAYMENT_DECLINED_COMPLIANCE">**PAYMENT\_DECLINED\_COMPLIANCE**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                | Cash App Pay detected a violation of terms of service, Program Rules, or applicable laws for the payment the API client is trying to create or capture. The payment is declined.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.<br /><br />No detail will be given as to what caused the compliance decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.                                                                                                                                                                  |
| <a id="PAYMENT_DECLINED_INSUFFICIENT_FUNDS" href="#PAYMENT_DECLINED_INSUFFICIENT_FUNDS">**PAYMENT\_DECLINED\_INSUFFICIENT\_FUNDS**</a><br />HTTP 400<br />Permanent (Do Not Retry)                       | The customer the API client is attempting to take a payment from does not have sufficient funds to complete the payment.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.                                                                                                                                                                                                                                                                                                                                                                                                          |
| <a id="PAYMENT_DECLINED_LIMIT_REACHED" href="#PAYMENT_DECLINED_LIMIT_REACHED">**PAYMENT\_DECLINED\_LIMIT\_REACHED**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                      | The customer the API client is attempting to take a payment from has reached the maximum amount of money they're allowed to spend from their account in a given time period.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.                                                                                                                                                                                                                                                                                                                                                      |
| <a id="PAYMENT_DECLINED_OTHER" href="#PAYMENT_DECLINED_OTHER">**PAYMENT\_DECLINED\_OTHER**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                               | The API declined the payment for an unknown reason. Used as a fallback when a more specific reason is not applicable.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.                                                                                                                                                                                                                                                                                                                                                                                                             |
| <a id="PAYMENT_DECLINED_RISK" href="#PAYMENT_DECLINED_RISK">**PAYMENT\_DECLINED\_RISK**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                                  | Cash App Pay detected this payment as having a high likelihood of fraud. The payment is declined.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.<br /><br />No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.                                                                                                                                                                                                                                                       |
| <a id="PAYMENT_DECLINED_CUSTOMER_BLOCKED_MERCHANT" href="#PAYMENT_DECLINED_CUSTOMER_BLOCKED_MERCHANT">**PAYMENT\_DECLINED\_CUSTOMER\_BLOCKED\_MERCHANT**</a><br />HTTP 400<br />Permanent (Do Not Retry) | The customer the API client is attempting to take a payment from has blocked the merchant from sending them payments. The payment is declined.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Reach out to Cash App Pay support if you need to know more about an individual decline.                                                                                                                                                                                                                                                                                                                                 |
| <a id="PAYMENT_INVALID_AMOUNT_MISMATCH" href="#PAYMENT_INVALID_AMOUNT_MISMATCH">**PAYMENT\_INVALID\_AMOUNT\_MISMATCH**</a><br />HTTP 400<br />Retryable with New Payload                                 | The amount the API client intended to created the payment with did not match the amount shown to the customer during the customer request for payment.<br /><br />The API client should consider this a retryable decline. Retrying the request with an amount that matches the one shown on the customer request will change the response. Grants are not consumed by this decline.                                                                                                                                                                                                                                                                                                          |
| <a id="PAYMENT_INVALID_CURRENCY_MISMATCH" href="#PAYMENT_INVALID_CURRENCY_MISMATCH">**PAYMENT\_INVALID\_CURRENCY\_MISMATCH**</a><br />HTTP 400<br />Retryable with New Payload                           | The currency the API client intended to created the payment with did not match the currency shown to the customer during the customer request for payment, or the currency of the merchant did not match the payment’s currency.<br /><br />The API client should consider this a retryable decline. Retrying the request with a currency that matches the one shown on the customer request and the one on the merchant will change the response. Grants are not consumed by this decline.                                                                                                                                                                                                   |
| <a id="PAYMENT_INVALID_TOO_LARGE" href="#PAYMENT_INVALID_TOO_LARGE">**PAYMENT\_INVALID\_TOO\_LARGE**</a><br />HTTP 400<br />Retryable with New Payload                                                   | The API declined the payment due to the amount being too high. The maximum payment size may be adjusted to prevent fraud, though this is not equivalent to a risk decline.<br /><br />The API client should consider this a retryable decline. Retrying the request with a lower amount may change the response. Grants are not consumed by this decline.                                                                                                                                                                                                                                                                                                                                     |
| <a id="PAYMENT_INVALID_TOO_SMALL" href="#PAYMENT_INVALID_TOO_SMALL">**PAYMENT\_INVALID\_TOO\_SMALL**</a><br />HTTP 400<br />Retryable with New Payload                                                   | The API declined the payment due to the amount being too low (below \$0.01 USD).<br /><br />The API client should consider this a retryable decline. Retrying the request with a larger amount may change the response. Grants are not consumed by this decline.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| <a id="REFUND_DECLINED_COMPLIANCE" href="#REFUND_DECLINED_COMPLIANCE">**REFUND\_DECLINED\_COMPLIANCE**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                   | Cash App Pay detected a violation of terms of service, Program Rules, or applicable laws for the refund the API client is trying to create or capture. The refund is declined.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.<br /><br />No detail will be given as to what caused the compliance decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.                                                                                                                                                                    |
| <a id="REFUND_DECLINED_OTHER" href="#REFUND_DECLINED_OTHER">**REFUND\_DECLINED\_OTHER**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                                  | The API declined the refund for an unknown reason. Used as a fallback when a more specific reason is not applicable.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.                                                                                                                                                                                                                                                                                                                                                                                                              |
| <a id="REFUND_DECLINED_RISK" href="#REFUND_DECLINED_RISK">**REFUND\_DECLINED\_RISK**</a><br />HTTP 400<br />Permanent (Do Not Retry)                                                                     | Cash App Pay detected this refund as having a high likelihood of fraud. The payment is declined.<br /><br />The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.<br /><br />No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.                                                                                                                                                                                                                                                        |
| <a id="REFUND_INVALID_CURRENCY_MISMATCH" href="#REFUND_INVALID_CURRENCY_MISMATCH">**REFUND\_INVALID\_CURRENCY\_MISMATCH**</a><br />HTTP 400<br />Retryable with New Payload                              | The currency the API client intended to create the refund with is invalid for one or more of the following reasons:<br />- The currency of the merchant does not match the currency of the refund<br />- The currency of the payment being refunded does not match the currency of the refund<br /><br />The API client should consider this a retryable decline. Retrying the request with a correctly-matched currency changes the response.                                                                                                                                                                                                                                                |
| <a id="REFUND_INVALID_PAYMENT_UNCAPTURED" href="#REFUND_INVALID_PAYMENT_UNCAPTURED">**REFUND\_INVALID\_PAYMENT\_UNCAPTURED**</a><br />HTTP 400<br />Retryable with New Payload                           | The API declined the refund because the linked payment has not been captured.<br /><br />The API client should void the original payment instead of issuing a refund.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| <a id="REFUND_INVALID_TOO_LARGE" href="#REFUND_INVALID_TOO_LARGE">**REFUND\_INVALID\_TOO\_LARGE**</a><br />HTTP 400<br />Retryable with New Payload                                                      | The API declined the payment due to the amount being too high. This could be due to a disputed payment which the merchant lost. The maximum payment size can be adjusted to prevent fraud, though this is not equivalent to a risk decline.<br /><br />The API client should consider this a retryable decline. Retrying the request with a lower amount may change the response. Grants are not consumed by this decline.                                                                                                                                                                                                                                                                    |
| <a id="REFUND_INVALID_TOO_SMALL" href="#REFUND_INVALID_TOO_SMALL">**REFUND\_INVALID\_TOO\_SMALL**</a><br />HTTP 400<br />Retryable with New Payload                                                      | The API declined the refund due to the amount being too low (below \$0.01 USD).<br /><br />The API client should consider this a retryable decline. Retrying the request with a larger amount may change the response. Grants are not consumed by this decline.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| <a id="REFUND_INVALID_SCOPE_MISMATCH" href="#REFUND_INVALID_SCOPE_MISMATCH">**REFUND\_INVALID\_SCOPE\_MISMATCH**</a><br />HTTP 400                                                                       | A payment/refund cannot be processed for this client because it has missing bank account configurations necessary for settlement purposes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| <a id="MISSING_SETTLEMENT_CONFIGURATION" href="#MISSING_SETTLEMENT_CONFIGURATION">**MISSING\_SETTLEMENT\_CONFIGURATION**</a><br />HTTP 400	<br />                                                        | A payment/refund cannot be processed for this client because it has missing configurations necessary for reporting purposes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Merchant & Brand Registration Errors

The following error codes may occur while managing merchants and brands on Cash App Pay.

All merchant registration errors have a category of `MERCHANT_ERROR` or `BRAND_ERROR`.

| Error Code                                                                                                                                                                   | Description and Resolution                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="BRAND_NOT_FOUND" href="#BRAND_NOT_FOUND">**BRAND\_NOT\_FOUND**</a><br />HTTP 400<br />Retryable with New Payload                                                      | The API client provided a brand ID in the request that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct brand ID in the request.<br /><br />Unless the brand ID parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request. |
| <a id="MERCHANT_MISSING_ADDRESS_OR_SITE" href="#MERCHANT_MISSING_ADDRESS_OR_SITE">**MERCHANT\_MISSING\_ADDRESS\_OR\_SITE**</a><br />HTTP 400<br />Retryable with New Payload | The API client tried to create or update a merchant and set both the address and site URL fields to null. Merchants require an address or site URL.<br /><br />The API client should set an address or site URL in the payload to resolve this error, then retry the request.                                                                                            |

## Grant Errors

The following error codes may occur while using any endpoint that interacts with grants, including ones used to create payments or refunds.

All grant errors have a category of `GRANT_ERROR`.

| Error Code                                                                                                                                                | Description and Resolution                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <a id="GRANT_ACTION_TYPE_MISMATCH" href="#GRANT_ACTION_TYPE_MISMATCH">**GRANT\_ACTION\_TYPE\_MISMATCH**</a><br />HTTP 400<br />Retryable with New Payload | The API found the provided grant and attempted to use it, but failed due to the grant's action not being compatible with the endpoint being called. The grant was not consumed.<br /><br />The API client should send the customer through the customer request flow with the correct action type for the endpoint it wants to call and generate a valid grant.          |
| <a id="GRANT_CONSUMED" href="#GRANT_CONSUMED">**GRANT\_CONSUMED**</a><br />HTTP 400<br />Retryable with New Payload                                       | The API found the provided grant and attempted to use it, but failed due to the grant being previously used (for one-time grants).<br /><br />The API client should send the customer through the customer request flow again to generate a fresh, unused, grant.                                                                                                        |
| <a id="GRANT_EXPIRED" href="#GRANT_EXPIRED">**GRANT\_EXPIRED**</a><br />HTTP 400<br />Retryable with New Payload                                          | The API found the provided grant and attempted to use it, but failed due to the grant having expired.<br /><br />The API client should send the customer through the customer request flow again to generate a fresh grant.                                                                                                                                              |
| <a id="GRANT_NOT_FOUND" href="#GRANT_NOT_FOUND">**GRANT\_NOT\_FOUND**</a><br />HTTP 400<br />Retryable with New Payload                                   | The API client provided a grant ID in the request that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct grant ID in the request.<br /><br />Unless the grant ID parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request. |
| <a id="GRANT_REVOKED" href="#GRANT_REVOKED">**GRANT\_REVOKED**</a><br />HTTP 400<br />Retryable with New Payload                                          | The API found the provided grant and attempted to use it, but failed due to the grant having been revoked.<br /><br />The API client should send the customer through the customer request flow again to generate a fresh grant.                                                                                                                                         |

## Dispute Errors

The following error codes may occur while using any endpoint that responds to disputes.

All dispute errors have a category of `DISPUTE_ERROR`.

| Error Code                                                                                                                        | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="DISPUTE_MISSING_EVIDENCE" href="#DISPUTE_MISSING_EVIDENCE">**DISPUTE\_MISSING\_EVIDENCE**</a><br />HTTP 400<br />Retryable | The request to challenge the dispute was valid and a dispute existed for the provided ID, but no evidence was found to challenge the dispute with. Since no evidence results in an automatic loss of the dispute, API clients are not allowed to "challenge" a dispute without evidence.<br /><br />If you want to respond to a dispute with no evidence, you should instead call the [AcceptDispute](/cash-app-pay-partner-api/api-reference/network-api/accept-dispute) endpoint, which makes the intent to "lose" the dispute explicit. Otherwise, upload evidence for the dispute and then re-attempt challenging it. |

## Webhook Errors

The following error codes may occur while using any webhook related endpoints.

All webhook errors have a category of `WEBHOOK_ERROR`.

| Error Code                                                                                                                                                | Description and Resolution                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="WEBHOOK_ENDPOINT_NOT_FOUND" href="#WEBHOOK_ENDPOINT_NOT_FOUND">**WEBHOOK\_ENDPOINT\_NOT\_FOUND**</a><br />HTTP 400<br />Retryable with New Payload | The API client provided a webhook endpoint ID in the request that could not be found or isn't owned by the client.<br /><br />The API client should ensure that it is passing the correct webhook endpoint ID in the request.<br /><br />Unless the webhook endpoint ID parameter is changed, the endpoint will continue to respond with a "not found" error and the client should not retry the request. |
| <a id="WEBHOOK_ENDPOINT_TOO_MANY" href="#WEBHOOK_ENDPOINT_TOO_MANY">**WEBHOOK\_ENDPOINT\_TOO\_MANY**</a><br />HTTP 400                                    | The maximum number of webhook endpoints for the client has been reached. Delete existing webhook endpoints before trying to create new ones.                                                                                                                                                                                                                                                              |

## Customer Errors

The following error codes may occur while using any customer-related endpoints.

All customer errors have a category of `CUSTOMER_ERROR`.

| Error Code                                                                                                                                       | Description and Resolution                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| <a id="CUSTOMER_DELETED_ACCOUNT" href="#CUSTOMER_DELETED_ACCOUNT">**CUSTOMER\_DELETED\_ACCOUNT**</a><br />HTTP 400<br />Permanent (Do Not Retry) | The customer account has been deleted. This is a permanent operation that cannot be revoked. |

## API Errors

In the rare event that the Cash App Pay APIs experience issues, the error codes below will be returned.

All server errors (ones not caused by the API client) have a category of `API_ERROR`.

| Error Code                                                                                                               | Description and Resolution                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="INTERNAL_SERVER_ERROR" href="#INTERNAL_SERVER_ERROR">**INTERNAL\_SERVER\_ERROR**</a><br />HTTP 500<br />Retryable | A general server error occurred, due to an issue with the API.<br /><br />The API client should retry its request. If errors continue, reach out to Cash App Pay support.                                       |
| <a id="SERVICE_UNAVAILABLE" href="#SERVICE_UNAVAILABLE">**SERVICE\_UNAVAILABLE**</a><br />HTTP 503<br />Retryable        | The API being called is experiencing an outage.<br /><br />The API client should retry its request. If errors continue, reach out to Cash App Pay support.                                                      |
| <a id="GATEWAY_TIMEOUT" href="#GATEWAY_TIMEOUT">**GATEWAY\_TIMEOUT**</a><br />HTTP 504<br />Retryable                    | The API was unable to process the request in a reasonable period of time and terminated the request.<br /><br />The API client should retry its request. If errors continue, reach out to Cash App Pay support. |

---

# Idempotency

How to work with idempotency keys and support retries without creating duplicate data

## What is idempotency?

Idempotency refers to the ability to call an endpoint multiple times and receive the same result, without causing additional side effects.

### Example: Handling a server error while creating a payment

When processing a payment, we want to prevent double-charging customers. Consider the following scenario, where an intermittent error in the Cash App Pay API requires the API client to retry a request:

![what-is-idempotency.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/what-is-idempotency.png)

1. API client tries to create a payment
2. Cash App Pay API responds with `HTTP 500`
3. API client retries creating a payment
4. Cash App Pay API responds with `HTTP 201 `

When the `HTTP 500` is returned, the API client doesn't know if a payment was created or not, because it doesn't have visibility into the cause of the error.

To prevent duplicates, the Cash App Pay API requires the API client to provide an `idempotency_key`, which acts as a unique identifier for the payment creation request. When the API client retries the request, if Cash App Pay already finds an existing payment created with the given `idempotency_key`, it will return it instead of creating one.

<Warning title="Very important">
  Idempotency keys are case-sensitive! Remember to verify the case-sensitivty of your 

  `idempotency_key`

   to avoid any issues or while troubleshooting.
</Warning>

## How do I generate an idempotency key?

Idempotency keys must be **1 to 64 characters long** and **unique** across all requests made to a single endpoint. We recommend using UUIDs for this, but any string that fits the requirements will work.

## How does the Cash App Pay API handle idempotency?

Every endpoint in the Cash App Pay API is idempotent, either implicitly (i.e., read operations) or explicitly (where an idempotency key is required).

<Warning>Idempotency keys are scoped to regions: Idempotency in the API is scoped to the `X-Region` header (see [Regions](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/regions-and-localization) for more info) provided in the request. This allows Cash App Pay to run in multiple regions at once and achieve higher availability and lower latencies.<br /><br />**Example:** <br /><br />With an `X-Region` of `PDX`, an API client creates an on file payment. The API client then retries the request with an `X-Region` of `IAD` <br />**Outcome:** 2 payments are created.<br /><br />*Make sure to always retry requests using the same X-Region header!*</Warning>
For all endpoints where an idempotency key is required, the Cash App Pay API will:

* **Scope the idempotent processing to the given `X-Region`**. Idempotency is not guaranteed to span across regions. If a request is retried with a different `X-Region` header, it may create duplicate data.
* **Enforce that an idempotency key is only associated with one payload.** If the payload is changed and the idempotency key stays the same, an [`IDEMPOTENCY_KEY_REUSED` error](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference#common-runtime-errors) is returned.
* **Cache HTTP 2XX responses and [permanent HTTP 4XX errors](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference)** for at least 30 days and return them on subsequent requests with the same idempotency key.

---

# Pagination

## What is pagination

When data sets get large, it becomes inefficient to return them in a single response. To make it faster for both the server and API clients, we divide the data into small chunks. The API client asks for a chunk of data, and the server returns it along with a token called a *cursor*. The API client then sends the cursor back to the server to request the next chunk of data. This process repeats until the API client has iterated through all the data and is called *pagination*.

## How does pagination work in the API?

All "list" endpoints in Cash App Pay use pagination, and support two pagination-related fields on the request:

* **`cursor`**, which is a string used by the server to fetch the next page of data. Use the `cursor` from the response to populate this field.
* **`limit`**, which is an integer from 1 to 100 that sets the maximum number of resources that can be returned in the response.

A `cursor` is provided at the top-level of each paginated response **if there is another page of data to load**. Once no cursor is present on the response, you've iterated through all the data.

### Example: Listing all payments

In this example, we'll attempt to list all the payments taken by our API client. First, we'll build a `cURL` request to call [list payments](/cash-app-pay-partner-api/api-reference/network-api/list-payments):

```json http
{
  "method": "get",
  "url": "https://sandbox.api.cash.app/network/v1/payments",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Client CLIENT_ID API_KEY_ID",
    "X-Region": "SEA",
    "X-Signature": "sandbox:skip-signature-check"
  },
  "query": {
    "limit": 1
  }
}
```

The API will respond with some JSON that looks like this:

```json
{
  "payments": [
    {
      "id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
      "amount": 1500,
      "refunded_amount": 100,
      "net_amount": 1400,
      "currency": "USD",
      "customer_id": "AUTH_24g7nq7m1je9b6fnzbtvwzqej",
      "merchant_id": "MERCHANT_4vxs5egfk7hmta3qx2h6rp91x",
      "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
      "status": "AUTHORIZED",
      "created_at": "2022-01-01T12:00:00Z",
      "updated_at": "2022-01-05T12:00:00Z",
      "refund_ids": [
        "PWCR_da1v3j4p3z15y47adpzzq0whj"
      ],
      "reference_id": "external-id"
    }
  ],
  "cursor": "be167132a9f2b565"
}
```

Since we set the `limit` parameter to `1`, only one resource is returned. To grab the next resource, we would make a similar request, but with the addition of the cursor as a query parameter:

```json http
{
  "method": "get",
  "url": "https://sandbox.api.cash.app/network/v1/payments",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Client CLIENT_ID API_KEY_ID",
    "X-Region": "SEA",
    "X-Signature": "sandbox:skip-signature-check"
  },
  "query": {
    "limit": 1,
    "cursor": "be167132a9f2b565"
  }
}
```

In the response, notice that there is no longer a `cursor` field:

```json
{
  "payments": [
    {
      "id": "PWC_50n21zyac0v2yhq23vvhk7xkwpc",
      "amount": 100,
      "net_amount": 100,
      "currency": "USD",
      "customer_id": "AUTH_24g7nq7m1je9b6fnzbtvwzqej",
      "merchant_id": "MERCHANT_4vxs5egfk7hmta3qx2h6rp91x",
      "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
      "status": "CAPTURED",
      "created_at": "2022-01-01T12:00:00Z",
      "updated_at": "2022-01-05T12:00:00Z",
      "reference_id": "external-id"
    }
  ]
}
```

This means that there is no more data to page through; we've now iterated through the entire data set.

---

# Reference IDs

The Cash App Pay API provides a `reference_id` field on all create, update, and upsert endpoints which can be used by an API client to set its own identifier for the resource. This allows API clients to establish a "link" between their systems and the Cash App Pay API.

All resources support querying by `reference_id` using "list" endpoints. If you lose the Cash App Pay-provided ID of a resource but have the `reference_id` from your systems, you can use this functionality to look up the Cash App Pay IDs of each resource.

## Requirements

Reference IDs must:

* Not contain any PII (personally identifiable information)
* Have between 1 and 1024 characters.

Reference IDs are required for brands and merchants. This prevents duplicate brands and merchants from being onboarded to Cash App Pay.

---

# Network API

The Network API helps developers manage payment processing, merchant registration, and dispute handling on Cash App Pay. It is an entirely server-side API, and cannot be called from a browser or point of sale device directly.

It requires API key authentication for every request, as well as a [X-Region](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/regions-and-localization) header.

## Endpoints

* Payments
  * [List payments](/cash-app-pay-partner-api/api-reference/network-api/list-payments)
  * [Retrieve payment](/cash-app-pay-partner-api/api-reference/network-api/retrieve-payment)
  * [Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)
  * [Void payment](/cash-app-pay-partner-api/api-reference/network-api/void-payment)
  * [Capture payment](/cash-app-pay-partner-api/api-reference/network-api/capture-payment)
  * [Void payment by idempotency key](/cash-app-pay-partner-api/api-reference/network-api/void-payment-by-idempotency-key)
* Refunds
  * [List refunds](/cash-app-pay-partner-api/api-reference/network-api/list-refunds)
  * [Retrieve refund](/cash-app-pay-partner-api/api-reference/network-api/retrieve-refund)
  * [Create refund](/cash-app-pay-partner-api/api-reference/network-api/create-refund)
  * [Void refund](/cash-app-pay-partner-api/api-reference/network-api/void-refund)
  * [Capture refund](/cash-app-pay-partner-api/api-reference/network-api/capture-refund)
  * [Void refund by idempotency key](/cash-app-pay-partner-api/api-reference/network-api/void-refund-by-idempotency-key)
* Merchants
  * [Create merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant)
  * [Upsert merchant](/cash-app-pay-partner-api/api-reference/network-api/upsert-merchant)
  * [Retrieve merchant](/cash-app-pay-partner-api/api-reference/network-api/retrieve-merchant)
  * [Update merchant](/cash-app-pay-partner-api/api-reference/network-api/update-merchant)
  * [List merchants](/cash-app-pay-partner-api/api-reference/network-api/list-merchants)
* Brands
  * [Create brand](/cash-app-pay-partner-api/api-reference/network-api/create-brand)
  * [Upsert brand](/cash-app-pay-partner-api/api-reference/network-api/upsert-brand)
  * [Retrieve brand](/cash-app-pay-partner-api/api-reference/network-api/retrieve-brand)
  * [Update brand](/cash-app-pay-partner-api/api-reference/network-api/update-brand)
  * [List brands](/cash-app-pay-partner-api/api-reference/network-api/list-brands)
* Customers
  * [Retrieve customer](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer)
  * [List customers](/cash-app-pay-partner-api/api-reference/network-api/list-customers)
  * [Retrieve customer grant](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer-grant)
  * [List customer grants](/cash-app-pay-partner-api/api-reference/network-api/list-customer-grants)
  * [Revoke customer grant](/cash-app-pay-partner-api/api-reference/network-api/revoke-customer-grant)
* Disputes
  * [List disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes)
  * [Retrieve dispute](/cash-app-pay-partner-api/api-reference/network-api/retrieve-dispute)
  * [Challenge dispute](/cash-app-pay-partner-api/api-reference/network-api/challenge-dispute)
  * [Accept dispute](/cash-app-pay-partner-api/api-reference/network-api/accept-dispute)
  * [List dispute evidence](/cash-app-pay-partner-api/api-reference/network-api/list-dispute-evidence)
  * [Retrieve dispute evidence](/cash-app-pay-partner-api/api-reference/network-api/retrieve-dispute-evidence)
  * [Create dispute evidence text](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-text)
  * [Create dispute evidence file](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file)
  * [Delete dispute evidence](/cash-app-pay-partner-api/api-reference/network-api/delete-dispute-evidence)
* Fee Plans
  * [List fee plans](/cash-app-pay-partner-api/api-reference/network-api/list-fee-plans)
  * [Retrieve fee plan](/cash-app-pay-partner-api/api-reference/network-api/retrieve-fee-plan)

---

# Customer Request API

The Customer Request API helps developers request permission from customers to perform actions on their accounts. It is accessible from browsers, servers, and point of sale devices to reduce latency, only requiring a client ID as authentication.

In general, most developers should opt to use Pay Kit instead of using the Customer Request API directly. However, if Pay Kit is not able to work with your existing codebase, you can fall back to this API to implement a near-identical experience.

## Visualization

The following figure shows the visualization of the Customer Request API with different entities being involved at various stages:

![customer Request API visualization](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/CustomerRequest-API-visualization.png)

## Endpoints

* Requests
  * [Create request](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request)
  * [Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)
  * [Update request](/cash-app-pay-partner-api/api-reference/customer-request-api/update-request)

---

# Management API

The Management API provides tools for developers to securely rotate the credentials for their integration in an automated way. It also provides the ability to created *scoped* API keys, which can be used in a microservices environment to give least-privileged access to different services calling the Cash App Pay API.

## Endpoints

* API Keys
  * [List API keys](/cash-app-pay-partner-api/api-reference/management-api/list-api-keys)
  * [Create API key](/cash-app-pay-partner-api/api-reference/management-api/create-api-key)
  * [Retrieve API key](/cash-app-pay-partner-api/api-reference/management-api/retrieve-api-key)
  * [Delete API key](/cash-app-pay-partner-api/api-reference/management-api/delete-api-key)
* Webhooks
  * [List webhook endpoints](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-endpoints)

  * [Create webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint)

  * [Retrieve webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/retrieve-webhook-endpoint)

  * [Update webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint)

  * [Delete webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/delete-webhook-endpoint)

  * [List webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events)

---

# Webhooks Overview

Cash App Pay has created webhooks so that you can subscribe to our events and get notified about them. When an event occurs, Cash App Pay collects data about the event, creates an event notification, and sends the event notification to the webhook endpoints that are subscribed to the event type.
<br /> <br />We currently support around 10 different webhook event types you can subscribe to. A single webhook endpoint can subscribe to many event types. Some examples of webhook events that you can subscribe to are: payment state changes, customer is created/updated, grants are created/updated, etc. For each event that occurs, Cash App Pay sends a POST request to your webhook endpoint URL with the event details (in JSON format).
<br /> <br />Examples of ways you can use webhooks as a third-party developer include:

* Subscribe to `dispute.created` and `dispute.state.updated` webhooks to process Cash App Pay disputes as they're created and updated in real time.
* Subscribe to `grant.status.updated` webhooks to process grant updates such as a customer revoking an on-file grant within Cash App.
  <br /> The webhook endpoint URL must expect JSON data from a POST request and confirm the successful receipt of that data.  To subscribe to our webhook events see [Create a webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint).
  For a list of all Cash App Pay API events that you can subscribe to, see `event_type` under [List Webhook Events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events).

## Webhooks API Operations

Cash App Pay provides the following webhook-related operations:

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Endpoints | [List webhook endpoints](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-endpoints) <br />[Create webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint) <br />[Retrieve webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/retrieve-webhook-endpoint)<br /> [Update webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint) <br />[Delete webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/delete-webhook-endpoint) |
| Events    | [List webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Static IP address

Webhooks from Cash App Pay originate from the following IP addresses. These are provided so you can allow access by these addresses through a firewall you are using.

* 52.43.5.66
* 35.160.162.127
* 35.164.233.105
* 52.201.69.179
* 18.215.196.131
* 18.235.28.71

## Before you start

* Define a URL that points to your application. Define an endpoint that directs webhook event notifications to your application.
* Allow traffic to ingress from Cash App Pay into the endpoint that you have defined so that it can receive the webhook events.
* Find out the Cash App Pay API version that your integration uses.
  <Note> The webhook events that you subscribe to must be supported by the API version you select. </Note>

## Requirements and limitations

To acknowledge the receipt of the event notification, the webhook endpoint URL must:

* accept HTTPS connection requests
* respond with a 2xx HTTP status code to Cash App Pay within the configured delivery timeout (defaults to 5 seconds)

You must update webhook endpoints with a new `api_key_id` when the previously assigned API key is rotated. See [Using API Keys](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/using-api-keys) for more details.

> Webhook events will not be successfully delivered for new domains until the new domain is allowlisted. New domains must be manually reviewed and allowlisted. It will typically take 1 business day to allowlist new domains. Contact Cash App Pay Partner Engineering Team if your URL is not allowlisted within the specified timeframe.

### SLA

Cash App Pay provides the following SLA for webhook event notifications:

* The initial event notification delivery will occur as soon as possible after the originating event
  > If the delivery times out, Cash App Pay will retry based on the table in Notification Retries.
* There is no guarantee of the delivery order of event notices.

### Notification retries

Cash App Pay assumes the delivery is unsuccessful in the following scenarios:

* A 2xx HTTP status code is not received within the delivery timeout field of the webhook endpoint subscription.
* A status code other than 2xx is returned.
  Cash App Pay retries the delivery of the event notification using exponential backoff for up to 72 hours after the originating event. After 72 hours, the notification is discarded and Cash App Pay does not attempt to resend the notification.

> Although this is true, you can still obtain the event notification by polling the [List Webhook Events endpoint](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events).

Cash App Pay uses exponential backoff to avoid spamming applications and retries notifications according to the schedule listed in the table below.

As an example, if Cash App Pay fails to deliver the event, it will try to send the event again in 1 second. If it fails again, it will try to send the event again in 1.15 seconds, which means that 2.15 seconds have elapsed since the initial attempt at delivery. Subsequent retries follow the retry schedule in the table below.

The exponential backoff retry policy is as follows:

* Interval: 1 second
* Exponent: 1.15
* Max Retries: 75

|               |                       |                          |              |              |
| ------------- | --------------------- | ------------------------ | ------------ | ------------ |
| Retry attempt | Time between attempts | Time since webhook event |              |              |
| 1             | 1 second              | 1 second                 |              |              |
| 2             | 1.15 seconds          |                          | 2.15 seconds |              |
| 3             |                       | 1.32 seconds             |              | 3.47 seconds |
| 4             |                       | 1.52 seconds             |              | 5.02 seconds |
| 5             | 1.75 seconds          | 6.77 seconds             |              |              |
| 6             | 2 seconds             | 8.77 seconds             |              |              |
| 7 – 75        | \~72 hours            | 72 hours                 |              |              |

---

# Webhooks: Steps

## Step 1: Create a Webhook Endpoint To Subscribe to Cash App Pay Webhook Events

The webhook endpoint URL must expect JSON data from a POST request and confirm the successful receipt of that data. To subscribe to our webhook events see [Create a webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint). For a list of all Cash App Pay API events that you can subscribe to, see `event_type` under [List Webhook Events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events).

The webhook endpoint must do the following:

* Receive a POST event notification.
* Respond with a 2xx HTTP status within the specified `delivery_timeout` (default 5 seconds).
* Accept HTTPS connections.
* Store the event notification data safely.
* Use the `event_id` field in the body of each event notification as an idempotency value. Your application should ignore any duplicate values.
* Use message versioning. If your application passes Cash App Pay event data to another application, you should add versioning to the data to avoid duplication and to make auditing of the data transfer easier.

<Note Title="Note">
  You can use a server endpoint as a webhook endpoint URL or you can create a serverless endpoint on services such as Amazon Web Services (AWS) or Google Cloud Platform. You can test a webhook endpoint URL with websites such as [https://webhook.site](https://webhook.site).
</Note>

### Format of an event notification

The following headers are included when making a POST request to the webhook endpoint to deliver the webhook event:

| Header                      | Value                                                                                                                                    | Description                                                                                                                                                                                                                                                         | Example                                                                                                                                           |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accept                      | `*/*`                                                                                                                                    | This [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) ensures that the API client and Cash App Pay API are communicating using the same MIME type in the response payload.                                                 | `*/*`                                                                                                                                             |
| Accept-Encoding             | `gzip`                                                                                                                                   | The Accept-Encoding request HTTP header indicates the content encoding (usually a compression algorithm) that the client can understand                                                                                                                             | `gzip`  \`                                                                                                                                        |
| Authorization               | `Client {CLIENT_ID} {KEY_ID}`                                                                                                            | This [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) is used to authenticate your API client with the                                                                                                                     | `Client CA-CI_CLIENT KEY_2f6cd0d5cc26b34ac878502`                                                                                                 |
| Content-Type                | `application/json; charset=utf-8`                                                                                                        | This [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) ensures that the API client and Cash App Pay API are communicating using the same MIME type in the request payload                                                   | `application/json; charset=utf-8`                                                                                                                 |
| Date                        | `{DATETIME_IN_RFC_1123_FORMAT}`                                                                                                          | Contains the date and time at which the message originated.                                                                                                                                                                                                         | Sun, 21 Oct 2018 12:16:24 GMT                                                                                                                     |
| Host                        | `{DOMAIN_OF_ENDPOINT_URL}`                                                                                                               | Specifies the host and port number of the server to which the request is being sent.                                                                                                                                                                                | `api.cash.app`                                                                                                                                    |
| X-Retry-Count               | `{NUMBER_OF_RETRIES}`                                                                                                                    | The number of times Cash App Pay has resent a notification for the given event (including the current retry) as an integer. The retry number does not include the original notification and is only present when there has been at least one unsuccessful delivery. | 3                                                                                                                                                 |
| X-Signed-Headers            | `Accept: */*, Content-Type: application/json; charset=utf-8, Host: {DOMAIN_OF_ENDPOINT_URL}, Authorization: Client {CLIENT_ID} {KEY_ID}` | The headers used to generate the X-Signature.                                                                                                                                                                                                                       | `Accept: */*, Content-Type: application/json; charset=utf-8, Host: api.cash.app, Authorization: Client CA-CI_CLIENT KEY_2f6cd0d5cc26b34ac878502 ` |
| X-Signature                 | `V1 hash({METHOD}\n{URL_PATH}\n{HEADERS}\n{BODY_DIGEST}) `                                                                               | An HMAC-SHA-256 signature used to validate the event authenticity. See more at [X-Signature](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/signing-requests) header.                                                                  | `V1 2bc29db277b0e2949f478691d33fe1f535a9832da90037a853ebb9d4a351cc1b`                                                                             |
| X-Delivery-Configuration-Id | `{WEBHOOK_ENDPOINT_ID} `                                                                                                                 | The Cash App Pay-provided ID of the webhook endpoint. This is returned when calling the [Create Webhook Endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint) API.                                                              | `WC_2f6cd0d5cc26b34ac8785026b14979 `                                                                                                              |

> **Webhook signatures:** Webhook deliveries also contain an X-Signature header that is computed using the same process as signing regular requests. This allows webhooks delivered by Cash App to be validated by computing the signature from the request payload and verifying that it matches the X-Signature header. See [Signing Requests](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/signing-requests) for more details.

The body of the webhook event has the following JSON schema:

|              |                                                                                                                                                                                         |                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Field        | Description                                                                                                                                                                             | Example                                                     |
| `type`       | The type of event that occurred.                                                                                                                                                        | `merchant.status.updated`                                   |
| `event_id`   | A unique identifier provided by Cash App for the event.                                                                                                                                 | `WE_78lusoltpu8r9shziq5hdnx96`                              |
| `created_at` | When this event occurred in RFC 3339 format (UTC).The time that the event is delivered may be significantly later than this timestamp due to webhooks being retried for up to 72 hours. | 2022-12-07T20:21:46.282Z                                    |
| `data`       | The data about the object that has a status change.                                                                                                                                     | See the next table for the attributes of the `data` object. |

The event’s `data` object contains the following attributes:

|          |                                                                            |                                |
| -------- | -------------------------------------------------------------------------- | ------------------------------ |
| Field    | Description                                                                | Example                        |
| `type`   | The name of the affected object's type.                                    | merchant                       |
| `id`     | The ID of the affected object.                                             | MMI\_4vxs5egfk7hmta3qx2h6rp91x |
| `object` | A JSON object containing the affected object's data relevant to the event. | See example code below         |

### Example code for the object

```json
{
      "id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
      "brand_id": "BRAND_8ereg0tug2yiik8vx24xpe5br",
      "name": "Example Business Name",
      "country": "US",
      "currency": "USD",
      "category": "5432",
      "reference_id": "external-id",
      "status": "ACTIVE",
      "created_at": "2022-01-01T12:00:00Z",
      "updated_at": "2022-01-05T12:00:00Z",
      "address": {
        "address_line_1": "1215 4th Ave",
        "address_line_2": "Suite 2300",
        "locality": "Seattle",
        "country": "US",
        "postal_code": "98161-1001",
        "administrative_district_level_1": "Washington"
      },
      "site_url": "http://example.com",
      "metadata": {}
}
```

### Example code for event notification `body`

```json
{
 "type": "merchant.status.updated",
 "event_id": "WE_78lusoltpu8r9shziq5hdnx96",
 "created_at": "2022-12-07T20:21:46.282Z",
 "data": {
   "id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
   "object": {
     "id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
     "brand_id": "BRAND_8ereg0tug2yiik8vx24xpe5br",
     "name": "Example Business Name",
     "country": "US",
     "currency": "USD",
     "category": "5432",
     "reference_id": "external-id",
     "status": "ACTIVE",
     "created_at": "2022-01-01T12:00:00Z",
     "updated_at": "2022-01-05T12:00:00Z",
     "address": {
       "address_line_1": "1215 4th Ave",
       "address_line_2": "Suite 2300",
       "locality": "Seattle",
       "country": "US",
       "postal_code": "98161-1001",
       "administrative_district_level_1": "Washington"
     },
     "site_url": "http://example.com",
     "metadata": {}
   },
   "type": "merchant"
 }
}
```

<br />

<br />

## Step 2: Verify and Validate Event Notifications in Sandbox

You can test webhook endpoints in our Sandbox environments both on an App and on the web. Go to the following links to learn more:

* [Sandbox App](/cash-app-pay-partner-api/guides/technical-guides/sandbox/sandbox-app)
* [Sandbox Web](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox)

## Step 3: Manage Webhook Operations

There are two aspects of Cash App Pay webhook events that you must understand:

* When are events triggered?
* How to manage event notifications?

For a list of all Cash App Pay API events that you can subscribe to, see `event_type` under [List webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events).

### Understand when events are triggered

Events that you can subscribe to using webhooks are generated by the various Cash App Pay applications and APIs. For example, during a sales transaction, several events could be generated including an updated payment received, customer created, grant declined, etc.

### Manage event notifications

When your webhook endpoint URL receives an event notification, you must respond within the specified delivery timeout (or default 5 seconds) to the POST and store the event information securely.

<Note>
   Cloud-based serverless applications, microservices, and function as a service (FaaS) applications let you handle event notifications without setting up a server. 
</Note>

## Step 4: Move Webhook Event Notifications to Production

When your application is ready to be moved from the Sandbox environment to production, there are several tasks you must complete to manage webhook event notifications in production. These include the following:

* Get production application credentials from the Cash App Pay Partner Engineering team.
  > The base URL for calling Sandbox endpoints is `sandbox.api.cash.app`. When you move your application to production, you need production credentials and you must use `api.cash.app` as the base URL.
* Update API calls to use the new credentials. Update your code to make API calls to Cash App Pay production endpoints.
* Use the `event_id` field in the body of each event notification as an idempotency value. Your application should ignore any duplicate values.
* Use message versioning. If your application passes Cash App Pay data to another application, you should add versioning to the data before passing it to avoid duplication and to make auditing of the data transfer easier.
* Validate the webhook event notification. A non-Cash App Pay POST can potentially compromise your application. All webhook notifications from Cash App Pay include an `X-Signed-Headers` and `X-Signature` header. See [Signing Requests](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/signing-requests) for more information.

## Handling a deleted customer webhook

The `customer.deleted` webhook event is delivered when a Cash App customer account is deleted.
This operation is often related to requests to forget a customer's data (for example, CCPA/GDPR), so that the customer
data in the webhook event does not contain any data that the customer provided (for example, a Cashtag). Since the
customer reference ID is provided by the API client, not the customer, any reference ID previously
attached to the customer will be included in the webhook event data.

When a customer account is deleted, all active grants for that customer are automatically revoked. Any
future attempts to use grants associated with that customer will fail. Any attempt to retrieve the customer
through the API will return a `CUSTOMER_DELETED_ACCOUNT` error.

<Note>
   As a best practice, when they receive a deleted customer webhook event, developers must delete any customer PII associated with the Cash App customer that was deleted. 
</Note>

---

# Webhook Signature Generation

A webhook signature is a cryptographic hash used to verify the authenticity and integrity of webhook requests. It ensures that the request comes from a trusted source and has not been tampered with.

Cash App Pay uses webhooks for the following events:

| Event Type                      | Trigger                                                                                                                                                                                                                     |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| customer.created                | When a Cash App user approves a client's Cash App Pay request for the first time.                                                                                                                                           |
| customer.deleted                | When a customer account is deleted by Cash App.                                                                                                                                                                             |
| customer.updated                | When a customer updates their Cashtag.                                                                                                                                                                                      |
| customer\_request.state.updated | When a customer request's state is updated. This is typically caused by a customer approving or declining the request.                                                                                                      |
| dispute.created                 | When a dispute is created. This happens when a customer files a dispute for a payment collected by a merchant.                                                                                                              |
| dispute.state.updated           | When a disputed status changes due to action taken by Block or the partner.                                                                                                                                                 |
| grant.created                   | When a grant is created. This happens when a customer request is approved.                                                                                                                                                  |
| grant.status.updated            | When a grant's status is updated. The status change can occur under these conditions:<br />• An API client-initiated action to create a payment or revoke a grant<br />• A customer revoking an extended-use grant          |
| merchant.status.updated         | When a merchant's status is updated.                                                                                                                                                                                        |
| payment.status.updated          | When a payment status is updated. The status change can occur under these conditions:<br />• An API client-initiated action to void or capture the payment<br />• A payment auto-voiding after 7 days of not being captured |
| refund.status.updated           | When a refund status is updated. The status change can occur under these conditions:<br />• An API client-initiated action to void or capture the refund<br />• A refund auto-voiding after 7 days of not being captured    |

For all events, the webhook needs a signature for security and verification purposes. Webhook signatures help:

* Prevent spoofing – They ensure only trusted sources can send webhooks
* Detect tampering – If the payload is altered, the signature will not match
* Add security – The signature works as an additional layer of protection alongside HTTPS.

## Pre-work

Before you can receive and act on webhooks, you need to do the following:

1. Set up a webhook endpoint and an associated URL. The endpoint must allow POST requests with content-type = application/json.
2. Create a Webhook endpoint using the [Create Webhook API](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint):
   ```
   curl --location 'https://sandbox.api.cash.app/management/v1/webhook-endpoints' \
   --header 'Accept: application/json' \
   --header 'Authorization: Client CASH_APP_CLIENT_ID API_KEY' \
   --header 'X-Region: PDX' \
   --header 'X-Signature: sandbox:skip-signature-check' \
   --header 'Content-Type: application/json' \
   --data '{
    "webhook_endpoint": {
         "event_configurations": [
       {
         "event_type": "grant.created",
         "api_version": "v1"
       },
       {
         "event_type": "grant.status.updated",
         "api_version": "v1"
       }
     ],
         "delivery_timeout": 10000,
         "api_key_id": "KEY_*",
         "url": "<webhook_url>",
         "reference_id": "reference_id"
    },
    "idempotency_key": "idempotency_key"
   }'
   ```
3. Ask your Cash App Pay Partner Engineering contact to allowlist the webhook URL.
4. Verify that your webhook is approved by querying the [Webhook Events API](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events):
   ```
   curl --location 'https://sandbox.api.cash.app/management/v1/webhook-endpoints' \
   --header 'Authorization: Client CASH_APP_CLIENT_ID API_KEY' \
   --header 'Accept: application/json' \
   --header 'X-Region: PDX' \
   --header 'X-Signature: sandbox:skip-signature-check'
   ```

## Verify the webhook event payload

To verify a webhook event payload with the HMAC value, follow these steps:

1. **Retrieve the webhook event signature:**
   * Retrieve the event signature from the `x-Signature` header provided in the webhook.
2. **Construct raw signature in canonical form:**
   * Get event method (e.g. POST)
   * Get the event handler path
   * Get the host
   * Construct headers with format: `{lowercase(name)}:{strip(value)}\n`
   * Hash event body
   * Concatenate raw signature with format:`${method}\n${path}\n${headers}\n${bodyDigest}`
3. **Generate HMAC-SHA-256 value:**
   * Create HMAC value using the raw signature and the API secret corresponding to API key utilities to create the webhook
   * Use a constant-time cryptographic library to generate the signature to prevent timing attacks
4. **Compare the generated signature with the received signature:**
   * Compare the computed signature against the `x-signature` header value
   * If both signatures match, then the request is verified as legitimate
   * If they don't match, reject the request

<Note Title="Note">
   The API secret is only available when a Webhook is created through  Cash App Pay APIs. If you lose the API secret, then update the Webhook with a new API key. 
</Note>

### Code sample:

```js
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

// Your API credentials
const CLIENT_ID = 'CAS-CI_*';
const API_KEY = 'KEY_*'; // API key used to create the webhook.
const API_SECRET = 'CASH_*'; // API secret generated when webhook was created.

function verifyWebhookSignature(req) {

 // Step 1: Retrieve signature from Webhook x-signature header.
 const signatureHeader = req.headers['x-signature'];
 if (!signatureHeader) return false;

 // Extract received signature (removing "V1 " prefix)
 const [version, receivedSignature] = signatureHeader.split(' ');
 if (version !== 'V1' || !receivedSignature) return false;

 // Step 2: Construct the raw signature in canonical form.
 const method = 'POST';
 const path = '/';
 const host = req.headers['host'];
 const headers = 'accept:*/*' + '\nauthorization:Client ' + CLIENT_ID + ' ' + API_KEY + '\ncontent-type:application/json; charset=utf-8' + '\nhost:' + host;
 const bodyDigest = crypto
  .createHash('sha256')
  .update(req.rawBody, 'utf8')
  .digest('hex');
 const rawSignature = `${method}\n${path}\n${headers}\n${bodyDigest}`;

 // Step 3: Create HMAC SHA-256 value.
 const expectedSignature = crypto
  .createHmac('sha256', API_SECRET)
  .update(rawSignature)
  .digest('hex');

 // Step 4: Assert recieved signature with expected signature.
 const receivedBuffer = Buffer.from(receivedSignature, 'hex');
 const expectedBuffer = Buffer.from(expectedSignature, 'hex');
 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
}

// Webhook endpoint
app.post('*', (req, res) => {
 if (!verifyWebhookSignature(req)) {
     return res.status(403).send("Invalid signature");
 }

 console.log("✅ Webhook verified:", req.body);
 res.status(200).send("Webhook received");
});

app.listen(80, () => {
 console.log('Webhook server listening on port 80');
});
```

---

# Payment Flow Operations

Cash App Pay (CAP) Payments follow a dual-message, authorization-capture model. Additionally, Payments require a separate Customer Request to complete a Payment.

Thus, there are three actions required to process a payment:

1. Customer request
2. Payment authorization
3. Payment capture

> For the purposes of this Payment Flow Operations section, M/PSP refers to a Merchant or PSP acting on behalf of a Merchant.",

## Customer Request and Grant

To get permission to initiate a Payment or issue a Refund, a M/PSP must obtain a Grant after receiving a Customer Request to use CAP. A Grant represents a Customer’s approval for a Merchant to take a specific Transaction-related action on their behalf. These actions are listed in **Action Types** below.

> Once a Grant is obtained, a M/PSP can perform the action on behalf of the Customer.",

### Action types

The following table describes what action is permitted with a Grant for each action type:

| Action             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ONE\_TIME\_PAYMENT | Initiate a one-time Payment from a Customer to a Merchant in a specified amount                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ON\_FILE\_PAYMENT  | Store a Customer's Cash App Account, allowing a M/PSP to create Payments or issue Refunds without requiring the Customer to repeat the Customer Request approval process.<br /><br />The scope of this Grant must be provided to and approved by the Customer, which determines which Merchants can use the on-file Payment Grant to initiate Payments or issue Refunds.  The scope of Grant may be at a Merchant, Brand, or PSP level. A Merchant-specific Grant may be used by a single merchant, a brand-level Grant may be used by any Merchant associated with the Brand, and a PSP-level Grant may be used by all Merchants managed by the PSP. |

![one-time-and-on-file-payment.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/one-time-and-on-file-payment.png)

## Payment Authorization

Authorizations are valid for and must be captured within seven days to complete a Payment. Authorizations not captured within seven days will be voided, and a new authorization will be required to complete a Payment.

Some Payment types require additional data during authorization:

* **Recurring Payments**: Authorizations for recurring payments should indicate that the Payment is part of a recurring series. Failure to do so may result in elevated decline rates.

### Payment Authorization Failure Scenarios & Codes

| Failure                                        | Code	Description                                                                                                                                                                                               |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GRANT\_CONSUMED                                | The Grant presented has already been used to take a Payment and cannot be reused.                                                                                                                              |
| GRANT\_EXPIRED                                 | The Grant presented is expired and cannot be used to take a Payment.                                                                                                                                           |
| GRANT\_NOT\_FOUND                              | The CAP API could not find the Grant presented.                                                                                                                                                                |
| GRANT\_REVOKED                                 | The Grant presented has been revoked and cannot be used to take a Payment.                                                                                                                                     |
| GRANT\_ACTION\_MISMATCH                        | The Grant presented is not usable for taking Payments. M/PSP must initiate a new Customer Request for Payment using a “ONE\_TIME\_PAYMENT” or “ON\_FILE\_PAYMENT” action.                                      |
| CUSTOMER\_DISABLED                             | The Cash App Account of the Customer authorizing the Payment is deactivated.                                                                                                                                   |
| MERCHANT\_DISABLED                             | Merchant is deactivated in CAP and cannot accept Payments. Merchants can be disabled by a PSP or Block.                                                                                                        |
| MERCHANT\_PENDING                              | Merchant onboarding has not yet completed and the merchant cannot accept Payments.                                                                                                                             |
| PAYMENT\_DECLINED\_COMPLIANCE                  | Payment is declined by Block for compliance reasons, including violation of Cash App Terms of Service, these [Program Rules](/cash-app-pay-partner-api/guides/partnerships/program-rules), or applicable laws. |
| PAYMENT\_DECLINED\_INSUFFICIENT\_FUNDS         | Customer does not have funds available to complete the Payment.                                                                                                                                                |
| PAYMENT\_DECLINED\_LIMIT\_REACHED              | Customer has reached a limit for the amount of funds that can be moved out of their Cash App Account during a given time period and must wait before making additional Payments.                               |
| PAYMENT\_DECLINED\_OTHER                       | Payment is declined for an unknown reason. Used as a fallback when a more specific reason is not applicable.                                                                                                   |
| PAYMENT\_DECLINED\_RISK                        | Payment is declined due to riskiness. Block’s risk models will decline Payments if they detect potentially fraudulent or otherwise risky activity.                                                             |
| PAYMENT\_DECLINED\_CUSTOMER\_BLOCKED\_MERCHANT | Payment is declined because the Customer has blocked the Merchant on Cash App.                                                                                                                                 |
| PAYMENT\_INVALID\_AMOUNT\_MISMATCH             | Payment amount did not match the amount shown to the Customer during Customer Request for Payment.                                                                                                             |
| PAYMENT\_INVALID\_CURRENCY\_MISMATCH           | Payment currency did not match the currency shown to the Customer during Customer Request for Payment, or the currency of the Merchant did not match the Payment’s currency.                                   |
| PAYMENT\_INVALID\_TOO\_LARGE                   | The requested Payment amount is too high. CAP’s maximum Payment size may be adjusted to prevent fraud, though this is not equivalent to a risk decline.                                                        |
| PAYMENT\_INVALID\_TOO\_SMALL                   | The requested Payment amount is too low (below \$0.01 USD).                                                                                                                                                    |

## Payment Capture

Once a Payment has been authorized, it must be captured within seven days to complete the Payment and trigger the settlement process for the M/PSP to receive funds.

Generally, a M/PSP must capture a Payment for the amount of authorization. A M/PSP may capture an amount that is different than the authorization value in two cases:

* Pre-authorization / Partial Capture
  * A M/PSP is mitigating Payment risk from a Customer before goods are delivered or services are rendered by authorizing an amount that will be higher than the final Payment value. For example, at gas stations, rental deposits.
* Over-Capture
  * A Merchant is including supplementary items to the original authorized Payment. This is typically used to add gratuity or other incidental fees. The amount of funds captured over the authorization amount is not guaranteed.

### Capture Failure Scenarios & Codes

Generally, once a Payment is authorized, the funds are safe for capture. However, a capture may fail after a successful authorization in the following scenarios.

| Failure Code                           | Description                                                                                                                                             |
| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PAYMENT\_DECLINED\_INSUFFICIENT\_FUNDS | Customer does not have funds available to complete the payment.                                                                                         |
| PAYMENT\_INVALID\_TOO\_LARGE           | The requested Payment amount is too high. CAP’s maximum Payment size may be adjusted to prevent fraud, though this is not equivalent to a risk decline. |
| PAYMENT\_INVALID\_TOO\_SMALL           | The requested Payment amount is too low (below \$0.01 USD).                                                                                             |
| GATEWAY\_TIMEOUT                       | The payment failed because it took too long to process.                                                                                                 |

## Refund

Refunds allow a M/PSP to send funds from a Merchant to a Customer.

Refunds are related to a previously captured Payment. They must not have an amount greater than the captured amount on the original Payment. There is no time limit to issue a Refund.

Refunds typically process in 7 to 10 business days following initiation. Transaction fees are not returned to the PSP in the event of a Refund.

### Refund Authorization

Authorizations are valid for and must be captured within seven days to complete a Refund. Authorizations not captured within seven days are voided, and a new authorization will be required to complete a Refund.

#### Refund Authorization Failure Scenarios & Error Codes

| Error Code                                | Description                                                                                                                                                                                                   |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PAYMENT\_NOT\_FOUND (linked refunds only) | Cash App could not find the Payment to Refund.                                                                                                                                                                |
| CUSTOMER\_DISABLED                        | The Cash App account of the Customer receiving the Refund is deactivated.                                                                                                                                     |
| MERCHANT\_DISABLED                        | Merchant is deactivated in CAP and cannot issue Refunds.                                                                                                                                                      |
| MERCHANT\_PENDING                         | Merchant onboarding has not yet completed and the merchant cannot issue Refunds.                                                                                                                              |
| REFUND\_DECLINED\_COMPLIANCE              | Refund is declined by Block for compliance reasons, including violation of Cash App Terms of Service, these [Program Rules](/cash-app-pay-partner-api/guides/partnerships/program-rules), or applicable laws. |
| REFUND\_DECLINED\_OTHER                   | Refund is declined for an unknown reason. Used as a fallback when a more specific reason is not applicable.                                                                                                   |
| REFUND\_DECLINED\_RISK                    | Refund is declined due to riskiness. Block’s risk models will decline Refunds if they detect potentially fraudulent or otherwise risky activity.                                                              |
| REFUND\_INVALID\_AMOUNT\_MISMATCH         | Refund amount did not match the amount shown to the Customer during Customer Request for Refund.                                                                                                              |
| REFUND\_INVALID\_CURRENCY\_MISMATCH       | Refund currency did not match the currency shown to the Customer during Customer Request for Refund, or the currency of the Merchant did not match the Refund’s currency.                                     |
| REFUND\_INVALID\_PAYMENT\_UNCAPTURED      | The Payment being refunded has not been captured and therefore cannot be refunded.                                                                                                                            |
| REFUND\_INVALID\_TOO\_LARGE               | The requested Refund amount is too high. CAP’s maximum Refund size may be adjusted to prevent fraud, though this is not equivalent to a risk decline.                                                         |
| REFUND\_INVALID\_TOO\_SMALL               | The requested Refund amount is too low (below \$0.01 USD).                                                                                                                                                    |

### Refund Capture

Once a Refund has been authorized, it must be captured within seven days to complete the Refund and trigger the settlement process. Refund captures only capture the **exact** amount that was authorized; Refunds may not be over or under-captured.

#### Refund Capture Failure Scenarios & Error Codes

Generally, once a Refund is authorized, it is safe for capture. However, a capture may fail after a successful authorization in the following scenarios:

| Error Code                   | Description                                                                                                                                                                                                   |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CUSTOMER\_DISABLED           | The Cash App account of the Customer receiving the Refund is deactivated.                                                                                                                                     |
| MERCHANT\_DISABLED           | Merchant is deactivated in CAP and cannot issue Refunds. Merchants can be disabled by a PSP or Block.                                                                                                         |
| REFUND\_DECLINED\_COMPLIANCE | Refund is declined by Block for compliance reasons, including violation of Cash App Terms of Service, these [Program Rules](/cash-app-pay-partner-api/guides/partnerships/program-rules), or applicable laws. |
| REFUND\_DECLINED\_OTHER      | Refund is declined for an unknown reason. Used as a fallback when a more specific reason is not applicable.                                                                                                   |
| REFUND\_DECLINED\_RISK       | Refund is declined due to riskiness. Block’s risk models will decline Refunds if they detect potentially fraudulent or otherwise risky activity.                                                              |

---

# On-file Payments

Cash App Pay has the  ability to support an on-file grant (Cashtag on file) for a Customer. This means that the on-file grant can be charged when the Customer makes future purchases.

This makes future purchases easier and quicker for the Customer, since they do not have to add their payment information and validate that information every time they make a transaction.

## On-file payment flow

### Step 1: Generate an on-file grant via Pay Kit

To create an on-file grant, you must specify an on-file payment action when creating the customer request. This action must include a `scope ID` and optionally an `account reference ID`.

See more information on [Scope ID](#scope-id) and [Account Reference ID](#account-reference-id) in [Important Terms](#important-terms).

### Example

```javascript
details.actions.onFile = {
  scopeId: 'brand_id_from_network_api',
  accountReferenceId: 'external_account_id',
};
```

<Note>
  If a valid on-file grant exists and a Cash App Customer approves a new on-file grant flow with the same Scope and Account Reference ID, the same Grant ID will be returned by the approved grant flow.
</Note>

### Step 2: Save Customer and grant information

An on-file grant cannot be retrieved via API. Therefore, on-file grants should always be stored at the time of grant creation; otherwise, the customer will have to generate a new on-file grant.

You can retrieve [Customer](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer) and [Grant](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer-grant) information if you have a valid `customer_id` and `grant_id`. Relevant customer information includes a customer's Cashtag and relevant grant information includes grant status and expiration date.

<br />

> If you are also saving a Customer's Cashtag, note that Cashtags are not static and can be changed up to 3 times. Ensure that Cashtags are correct by subscribing to `customer.updated` webhooks. Cashtags are not considered PII and should be displayed in your checkout flow and in the customer's account settings. See our [brand guidelines](/cash-app-pay-partner-api/guides/resources/cash-app-pay-assets) for more details.

```curl
curl --request GET \
    --url https://sandbox.api.cash.app/network/v1/customers/customer_id \
    --header 'Authorization: Client api_key' \
    --header 'X-Region: PDX' \
    --header 'accept: application/json'
```

<br />

```curl
curl --request GET \
     --url https://sandbox.api.cash.app/network/v1/customers/customer_id/grants/grant_id \
     --header 'Authorization: Client api_key' \
     --header 'X-Region: PDX' \
     --header 'accept: application/json'
```

### Suggested disclaimer copy for \$Cashtag on-file

Cash App Pay suggests that you add this disclaimer when a customer selects \$Cashtag on-file for payment:

> By continuing, you authorize **`{{Merchant Name}}`** to debit your Cash App account for this payment and future payments in accordance with **`{{Merchant Name}}`**'s terms, until this authorization is revoked. You can change this authorization anytime in your Cash App Settings.

### Step 3: Authorize an on-file payment

Once an on-file grant has been successfully created, you can immediately use the grant to authorize a payment or simply save the grant for use in the future.

```curl
curl --request POST \
     --url https://sandbox.api.cash.app/network/v1/payments \
     --header 'Authorization: Client api_key' \
     --header 'X-Region: PDX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "payment": {
         "capture": true,
         "amount": 1234,
         "currency": "USD",
         "merchant_id": "merchant_id",
         "grant_id": "onfile_grant",
         "reference_id": "external-id"
    },
    "idempotency_key": "random_uuid"
}
```

### Step 4: Revoking an on-file grant

Once an on-file grant is created, it can be used to create payments on behalf of the Customer for 10 years. If, for whatever reason the grant needs to be revoked, you can use the [revoke customer grant](/cash-app-pay-partner-api/api-reference/network-api/revoke-customer-grant) endpoint to prevent the grant from being used for future payments.

<br />

```curl
curl --request POST \
     --url https://sandbox.api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke \
     --header 'Authorization: Client api_key' \
     --header 'X-Region: PDX' \
     --header 'accept: application/json'
```

<br />

Also, a Customer can remove the businesses with whom they have active on-file grants. Cash App provides [grant.status.updated](/cash-app-pay-partner-api/api-reference/network-api/grant-status-updated) webhooks to alert Partners when any change to the on-file grant happens.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/remove-on-file-grant.png" alt="Remove on file grant" noZoom />

## Important terms

### Scope ID

The scope of an on-file grant determines which Merchants have the ability to authorize a payment with the grant. The `scope_id` can be set to one of these:

* **Client:** The grant from a Client-scoped on-file action can be used to create a payment for any Merchant owned by the Client.
  * **Client example:** A PSP provides a hosted wallet solution where Customers can save payment methods on-file and use these payment methods to seamlessly checkout with Merchants supported by the PSP.
* **Brand:** The grant from a Brand-scoped on-file action can be used to create a payment for any Merchant that has a matching Brand ID.
  * **Brand example:** A specific Merchant wants to support Cashtag on-file for their customers.

### Account Reference ID

The Account Reference ID represents the identifier of the Account or Customer associated with the on-file action. Attempting to create a new on-file grant with the same Scope but different Account Reference ID will result in a new unique on-file grant.

**Example:**  A Cash App Customer and their partner have separate accounts on a popular e-commerce website. They both want to save the same Cash App account on-file for their separate accounts. Account reference ID allows the e-commerce website to generate a unique on-file grant for each of these customer accounts - each grant can be managed independently and access can be revoked for one account without removing access to the other.

## Merchant eligibility

Reach out to the Partner Engineering team or your Cash App Point of Contact to check if you are eligible to set up \$Cashtag on-file payments for your Customers.

---

# Incremental Authorization

Incremental authorization lets merchants request an increase to the authorized amount for a pending Cash App Pay payment. If the payment is eligible and the Cash App customer has additional funds available, Cash App increases the authorization to the higher amount requested by the merchant.

For example, a customer authorizes \$20 for a food delivery order. During fulfillment, they add items worth \$10. Instead of creating a new payment, you can increase the existing authorization to \$30.

<Note>
  To implement incremental authorization, you must use deferred capture (separate authorization and capture steps). Contact the [Cash App Pay Partner Engineering Team](https://afterpay.formstack.com/forms/global_merchant_technical_support) to request access.
</Note>

Incremental authorization is available for both one-time and on file payments.

## Set up incremental authorization

### Step 1: Create a payment authorization

Call the Create Payment endpoint [(/v1/payments)](/cash-app-pay-partner-api/api-reference/network-api/create-payment) to create a payment authorization. Set `capture` to `false`.

### Step 2: Update the payment authorization

Call the Create Incremental Authorization endpoint [(v1/payments/\{payment\_id}/authorizations)](/cash-app-pay-partner-api/api-reference/network-api/create-payment-authorization) with the updated amount. `amount` must be greater than or equal to the current authorized amount, and must follow the limits described above.

When the authorized amount is updated, the customer is notified via email, SMS, or push notification.

### Step 3: Capture payment

Within 7 days of creating the payment authorization, call the Capture Payment endpoint [(/v1/payments/\{payment\_id}/capture)](/cash-app-pay-partner-api/api-reference/network-api/capture-payment) to capture the final payment.

<Note>
  You can also void the payment by calling [/v1/payments/\{payment\_id}/void](/cash-app-pay-partner-api/api-reference/network-api/void-payment).
</Note>

```mermaid
flowchart TD
    A[Start] --> C[One-time Payment Grant]
    A --> D[On File Payment Grant]
    
    C --> E[Create Payment]
    D --> E
    
    E --> F[Create Incremental Authorization]
    
    F --> G[Capture Payment]
    
    G --> H[Complete]
    
    style A fill:#ffffff,stroke:#000000
    style C fill:#ffffff,stroke:#000000
    style D fill:#ffffff,stroke:#000000
    style E fill:#ffffff,stroke:#000000
    style F fill:#ffffff,stroke:#000000
    style G fill:#ffffff,stroke:#000000
    style H fill:#ffffff,stroke:#000000
```

## Limits

* You can incrementally increase the amount up to 10 times per payment
* Authorization increases are limited to \$500 or 500% of the previous amount, whichever is higher
* Increases must be captured within the expiration window of the original payment authorization (default 7 days)

---

# Disputes

## Dispute filing

Disputes can only be initiated by a Customer. Customers may file a Dispute in two ways:

* For Payments originating from a **linked instrument**, Customers may file Disputes directly with their issuing financial institution or with Block directly through Cash App.
* For Payments originating from a **Cash App stored balance**, Customers must file Disputes with Block directly through Cash App.

## Merchant expectations

Merchants are expected to make a good faith attempt to resolve any issues associated with a Transaction to minimize the number of Disputes filed by Customers. Merchants are expected to be a Customer’s first point of contact for issues, grievances, and other Customer support issues related to a Transaction.

## Dispute notification and types

PSPs will receive notifications about the following types of Disputes. Such notifications will be sent via the CAP Disputes Report, as detailed in the technical documentation available on the Developer Portal. The PSP is able to choose whether, when, and how to respond to Disputes as noted below.

<br />

<table>
  <thead>
    <tr>
      <th>
        Code
      </th>

      <th>
        Description
      </th>

      <th>
        PSP Requirements
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        FR10
      </td>

      <td>
        Customer has no knowledge of the Payment.
      </td>

      <td>
        PSPs will receive notification with no action required, and the disputed payment will be settled back to the PSP. No dispute fee will be charged.
      </td>
    </tr>

    <tr>
      <td>
        FR11
      </td>

      <td>
        Customer has no knowledge of the Payment and liability has shifted to the Merchant due to collusion, fraud monitoring program thresholds, or any other reason.
      </td>

      <td rowspan="8">
        PSPs will receive notification with a due date for response.Response and supporting materials are required for adjudication. 

        <br />

        <br />

        Supporting materials may be provided in one or more of the following formats: PDFs, JPEG / GIF / PNG / TIFF / HEIF / HEIC images, and plain text. PSP will be liable for any Dispute accepted, ignored, or decided in the Customer’s favor.
      </td>
    </tr>

    <tr>
      <td>PE10</td>\
      <td>Payment was processed twice.</td>
    </tr>

    <tr>
      <td>PE11</td>\
      <td>Payment amount differs from agreed amount.</td>
    </tr>

    <tr>
      <td>PE12</td>\
      <td>Customer paid by other means.</td>
    </tr>

    <tr>
      <td>CD10</td>\
      <td>Canceled services.</td>
    </tr>

    <tr>
      <td>CD11</td>\
      <td>Goods or services differ from what was agreed upon for the Payment.</td>
    </tr>

    <tr>
      <td>CD12</td>\
      <td>The goods or services were not received.</td>
    </tr>

    <tr>
      <td>CD13</td>\
      <td>The purchase was canceled or returned, but the Refund has not been processed.</td>
    </tr>
  </tbody>
</table>

<br />

## Dispute timelines

PSPs must provide responses to Disputes within the aforementioned timeframe. Failure to respond within that timeframe will result in the Dispute being decided in the Customer’s favor and liability assumed by the PSP for the disputed Payment(s).

<br />

| Reason Code            | Max days for Customer to open a Dispute                                                                     | Max days for PSP response  (post notification from Block) | Max days for resolution  (post PSP response) |
| :--------------------- | :---------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------- | :------------------------------------------- |
| FR10, FR11             | Up to 120 days post Payment date                                                                            | 13                                                        | 45                                           |
| CD11, CD12             | Up to 120 days post Payment date or expected receipt of goods/services (max 540 days from transaction date) | 13                                                        | 45                                           |
| CD13                   | Up to 120 days post Payment date or date of cancellation                                                    | 13                                                        | 45                                           |
| PE10, PE11, PE12, CD10 | Up to 120 days post Payment date                                                                            | 13                                                        | 45                                           |

<br />

### Dispute holds and fees

The amount of any Dispute will be debited from settlement amounts owed to PSPs at the time of Dispute notification. The funds will be disbursed to the PSP at the end of the Dispute process if the outcome is in favor of the PSP.

PSPs will be charged a fee for each Dispute received, regardless of the outcome of any review and adjudication of that Dispute. Disputes resulting from unauthorized Payments for which Block will assume liability will not incur such a fee.

---

# Dispute Lifecycle

The Cash App Pay dispute process exists to protect our customers from bad actors and merchant errors. Customers have the option to dispute any Cash App Pay transaction, which will initiate the dispute process.

## RESPONSE\_REQUIRED

New disputes will be created in the `RESPONSE_REQUIRED` state where our systems will wait for text and file-based evidence to be submitted by the merchant, or for the merchant to accept the dispute without contest. The merchant can upload any information to help decide the outcome of the dispute.

<br />When all evidence has been submitted, the dispute may be challenged to start the adjudication process. The dispute will move to the `PROCESSING` state where it will remain until the dispute is adjudicated.
<Note> On the 13th day, we will automatically challenge any dispute with evidence. Any disputes without evidence, will be lost after 13 days. </Note>
Alternatively, the dispute may be accepted by the merchant to complete processing and transition immediately to the ACCEPTED state. When a dispute is created, the disputed amount will be withheld from that day’s settlement until the settlement following a resolution.

## PROCESSING

Disputes that have been challenged with evidence will show up in the processing state while they await adjudication, which can take up to 45 days.
<Note> During this time, you cannot submit any more evidence to the challenged disputes. </Note>
Once a dispute has been adjudicated, it will end up in one of the following terminal states:

* WON
* PARTIALLY\_WON
* LOST

<Note>
   See 

  [Dispute timelines](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/introduction#dispute-timelines)

   for the length of time a Merchant has to respond before the dispute is forfeited. 
</Note>

## WON

A dispute will transition to the `WON` state if the dispute has been adjudicated in favor of the merchant or the customer withdraws their dispute.

In either case, merchants will be reimbursed their withheld settlement for this dispute at the next settlement.

## PARTIALLY\_WON

A dispute will transition to the `PARTIALLY_WON` state if the dispute has been adjudicated in favor of the customer for less than the disputed amount. The amount lost will be communicated to merchants via dispute reports and the amount lost will not be reimbursed to the merchant at the next settlement.

## LOST

A dispute will transition to the `LOST` state if the dispute has been adjudicated in favor of the customer for the entire disputed amount. The amount lost will be communicated to merchants via dispute reports and merchants will not receive their withheld settlement for this dispute.

## ACCEPTED

A dispute will transition to the `ACCEPTED` state if the merchant chooses to forgo the adjudication process and accept an automatic loss of the dispute. The amount lost will be communicated to merchants via dispute reports and merchants will not receive their withheld settlement for this dispute.

## NO\_RESPONSE\_REQUIRED

A dispute will be created in the `NO_RESPONSE_REQUIRED` state if Cash App has accepted liability for the dispute. These disputes are displayed via the API for transparency, however, the merchant is not obligated to take any action and is not liable for the dispute.

## State Machine

![disputes-payment-flow.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/disputes-payment-flow.png)

---

# Dispute Reports

Dispute reports provide an easy-to-read document to see the current status of all disputes listed by merchant. These reports are available in CSV format and are automatically generated and uploaded securely to your server according to the configuration set up during your integration onboarding process.

<Note>
  We strongly recommend that Payment Service Providers monitor these dispute reports on a regular schedule. Use the information gathered as a failsafe mechanism to ensure that merchants are aware of all Cash App Pay disputes.

  This is useful if your normal method of informing merchants about disputes ever fails. You can use the information in the report to ensure disputes information is correctly captured and merchants are aware of these disputes.
</Note>

For more details on configuring your dispute reporting integration, contact your Cash App engineering partner.

## Configuring Dispute Reports

Reports are uploaded by Cash App to a client-provided SFTP server. The following information is required.

* SFTP hostname
* SFTP port
* username
* SFTP user's private key
* SFTP server host's public key (optional)
* filepath (for uploading the reports)
  Reports are in CSV format and use a utf-8 encoding.

Each dispute report is given a unique filename to avoid upload collisions using the following convention:
`yyyyMMdd_dispute_report_client_<clientID>_batch_<batchToken>_chunk_<chunkID>.csv`

<Note>
  As an additional security benefit, Cash App Pay can optionally PGP encrypt disputes files before they’re uploaded to the client SFTP server. In order to enable this feature, please contact [Cash App Partner Engineering](mailto:cash-app-partner-engineering@squareup.com).
</Note>

## CSV Schema

Dispute report files can contain up to 9,999 records. Each file will contain headers in the top row, and then each subsequent row will have the following schema:

| Column Name                | Type                                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dispute\_id                | String                                                                                                                    | Unique identifier for this dispute assigned by Cash App                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| dispute\_created\_at       | String<br />(datetime using RFC 3339 standard in UTC)                                                                     | The time at which the dispute was created                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| dispute\_updated\_at       | String<br />(datetime using RFC 3339 standard in UTC)<br /> <br /> Note: This field is optional, so it may not be present | The time at which the dispute was updated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| merchant\_id               | String                                                                                                                    | Unique identifier of the merchant (assigned by Cash App) that received this payment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| merchant\_reference\_id    | String                                                                                                                    | Unique identifier for the merchant, as provided by the PSP                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| dispute\_reason            | String                                                                                                                    | 4-digit code consisting of 2 letters followed by 2 numbers that indicates why the dispute was created, at a high level.<br /> <br />**Current values:**<br />FR10: Customer has no knowledge of the payment.<br />  FR11: Customer has no knowledge of the payment and liability has shifted to the merchant due to collusion, fraud monitoring program thresholds, or any other reason.<br />  PE10: Payment was processed twice.<br />PE11: Payment amount differs from agreed amount.<br />PE12: Payment was paid for by another means.<br />  CD10: Cancelled services.<br />  CD11: Goods or services differ from what was agreed upon for the payment.<br />CD12: The goods or services were not received.<br />  CD13: The purchase was cancelled or returned, but the refund has not been processed. |
| dispute\_currency          | String                                                                                                                    | Indicates the currency associated with the dispute. Values are from the ISO-4217 Alpha-3 specification.<br /> <br />**Current values:**<br />  USD: United States Dollar                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| payment\_id                | String                                                                                                                    | Unique identifier for this payment issued by Cash App                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| payment\_reference\_id     | String<br />Note: This field is optional, so it may not be present                                                        | A user-defined identifier for this payment, typically used to associate the payment with a record in an external system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| dispute\_amount            | Number(Integer)                                                                                                           | Amount of disputed money, in the lowest denomination of currency on the associated payment                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| settlement\_amount         | Number(Integer)                                                                                                           | Signed amount that will be settled as a side effect of this dispute update, in the lowest denomination of currency for the dispute.<br />Positive amounts denote funds being withheld from the PSP. Negative amounts denote previously withheld funds being returned to the PSP (in cases where the merchant at least partially won the dispute)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| dispute\_state             | String                                                                                                                    | The step in the [Dispute Life Cycle](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/dispute-life-cycle) that this dispute is currently at:<br /> RESPONSE\_REQUIRED<br />  NO\_RESPONSE\_REQUIRED<br />  PROCESSING<br />  ACCEPTED<br />  WON<br />  PARTIALLY\_WON<br />  LOST                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| dispute\_response\_due\_at | String<br />(datetime using RFC 3339 standard in UTC)<br />Note: This field is optional, so it may not be present         | The time at which the dispute must be challenged by, after which it will be automatically accepted (read more about the [Dispute Life Cycle](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/dispute-life-cycle)).<br />This field will be empty if no action is required by the PSP                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Example Data

The following snippets present example data for different dispute-related scenarios. For more details on the different dispute states and flows, please refer to the [Dispute Life Cycle](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/dispute-life-cycle).

### Credit Disputes

```CSV
dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gdfsm,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE10,USD,PWC_zw52d1jy9cj9w1cx803qjjrkl,PXJT_347,4600,4600,RESPONSE_REQUIRED,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gdfsm,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE10,USD,PWC_zw52d1jy9cj9w1cx803qjjrkl,PXJT_347,4600,0,PROCESSING,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gdfsm,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE10,USD,PWC_zw52d1jy9cj9w1cx803qjjrkl,PXJT_347,4600,0,LOST
```

### Dispute ruled in favour of merchant

```CSV
dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gagdq,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE11,USD,PWC_zw52d1jy9cj9w1cx803qjwrck,XJ9_42,3797,3797,RESPONSE_REQUIRED,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gagdq,2021-10-25T22:05:34.925Z,2021-10-26T10:35:21Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE11,USD,PWC_zw52d1jy9cj9w1cx803qjwrck,XJ9_42,3797,0,PROCESSING,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gagdq,2021-10-25T22:05:34.925Z,2021-10-27T15:27:01Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE11,USD,PWC_zw52d1jy9cj9w1cx803qjwrck,XJ9_42,3797,-3797,WON
```

### Dispute ruled in favour of merchant for less than total dispute amount

```CSV
dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gwwjd,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,CD11,USD,PWC_zw52d1jy9cj9w1cx803qjbeck,1299,1299,RESPONSE_REQUIRED,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gwwjd,2021-10-25T22:05:34.925Z,2021-10-26T12:37:52Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,CD11,USD,PWC_zw52d1jy9cj9w1cx803qjbeck,1299,0,PROCESSING,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gwwjd,2021-10-25T22:05:34.925Z,2021-10-30T17:57:02Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,CD11,USD,PWC_zw52d1jy9cj9w1cx803qjbeck,1299,-200,PARTIALLY_WON
```

### Fraud Disputes

```CSV
dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gwgdq,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,FR10,USD,PWC_zw52d1jy9cj9w1cx803qjattk,T1000_azerty,4600,0,NO_RESPONSE_REQUIRED
```

> Fraud disputes where Cash App Pay takes on liability are included here for informational purposes only and do not impact settlement.

---

# Settlement

Cash App settles [captured payments](/cash-app-pay-partner-api/api-reference/network-api/capture-payment) with the PSP (Payment Service Provider) client (also referred to as client in the technical specifications below) via ACH using a batch process. We capture the transaction-level details of each Settlement  as a Reconciliation report and upload them to a client-provided SFTP server.

<Note>
   Cash App will provide a net Settlement process, deducting Refunds and Dispute amounts from Settlement amounts. 
</Note>

Cash App will deliver funds to the client for all unsettled eligible transactions before a configurable designated cutoff time. The Settlement process follows the [Federal Reserve calendar](https://www.federalreserve.gov/aboutthefed/k8.htm) for availability. Which means that, Settlement is not available on Saturdays, Sundays, and holidays.

<Note>
   Settlement for Cash App Pay Transactions captured prior to 11:00 PM UTC will be initiated the same business day, subject to U.S. federal holidays. 
</Note>

For each daily batch of processed transactions that must be settled (i.e., CAPTURE, REFUND, CHARGEBACK), Cash App will issue a single-batched ACH Transfer with the client's configured Bank account as the destination. Each settlement includes an ACH payment and a series of associated Reconciliation reports that can contain up to 9,999 transactions per report.

| Property            | Type                                                                        | Description                                                                                                                                                                  |
| :------------------ | :-------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Settlement Time     | String <br />The time in a 24-hour clock ("hh:mm") in UTC (ISO 8601-1:2019) | This is the cutoff time for settling any unsettled eligible transactions. The batch will span the previous cutoff (on a business day) to the current one. (default: "23:00") |
| Bank routing number | String <br />ABA routing transit number is nine numerical digits            | This is the routing number of the destination bank where the funds will be deposited via ACH (required)                                                                      |
| Bank account number | String                                                                      | This is the account number of the destination bank where the funds will be deposited via ACH (required)                                                                      |

## Reconciliation Reports

Each net Settlement will have a corresponding Reconciliation report showing the amount of each Payment, applicable fees, Refunds, and Dispute-related adjustments used in the calculation of the Settlement amount. This report is delivered daily via Secure File Transfer Protocol (SFTP) to the PSP.
Cash App uploads Reconciliation reports to a client-provided SFTP server. To do this, we want the following information:

* SFTP hostname

* SFTP port

* Username of the PSP's SFTP server

* SFTP user's private RSA key

* SFTP server host's public RSA key (optional)

* Destination folder path (filepath for uploading the reports)

<br />

<Note>
   Reports are in CSV format and use a UTF-8 encoding. 
</Note>

<Note>
  As an additional security benefit, Cash App Pay can optionally PGP encrypt settlement files before they’re uploaded to the client SFTP server.
</Note>

<br />

## Activity Reconciliation Report

We give each activity Reconciliation report  a unique filename to avoid upload collisions using the following convention:\
`<yyyymmdd>_settlement_report_client_<client-id>_batch_<batch-id>_chunk_<chunk index>.csv`

<br />

> `<yyyymmdd>` is the date of settlement for settlement batch. For manually generated activity reconciliation reports, `<yyyymmdd>` is the date the report was generated.

<br />

### CSV Schema

Activity Reconciliation report files can contain up to 9,999 records. Each file will contain headers in the top row, and then each subsequent row will have the following schema:

| Column Name             | Type                                             | Description                                                                                                                                                                                    |
| :---------------------- | :----------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| merchant\_id            | String                                           | Cash App identifier for the associated Merchant.                                                                                                                                               |
| merchant\_reference\_id | String                                           | Client-provided reference ID specified on the Merchant associated with the payment or refund.                                                                                                  |
| settlement\_batch\_id   | String                                           | Cash App identifier of the batch of transactions this transactions was settled with. If possible, this identifier will be forwarded as metadata with the ACH transfer settling this payment.   |
| payment\_id             | String                                           | Cash App identifier for the associated payment. This identifier can be used to cross-reference settlement transactions of type `CHARGEBACK` with the associated dispute on the Dispute report. |
| payment\_reference\_id  | String                                           | Client specified reference id during [payment creation](/cash-app-pay-partner-api/api-reference/network-api/create-payment)                                                                    |
| refund\_id              | String                                           | Cash App identifier for the associated refund.                                                                                                                                                 |
| refund\_reference\_id   | String                                           | Client specified reference id during [refund creation](/cash-app-pay-partner-api/api-reference/network-api/create-refund)                                                                      |
| dispute\_id             | String                                           | Cash App identifier for the associated dispute                                                                                                                                                 |
| transaction\_type       | String                                           | The type of transaction {`CAPTURE`, `REFUND`, `CHARGEBACK`}                                                                                                                                    |
| transaction\_time       | String(datetime using RFC 3339 standard in UTC)  | The time at which the transaction event occurred. **NOTE**: for `CAPTURE`, this is the time of capture, for `REFUND`, it is the time of refund, etc.                                           |
| net\_amount             | Number (Integer)                                 | The net amount (after fees) being settled for this transaction event.                                                                                                                          |
| gross\_amount           | Number (Integer)                                 | The gross amount of the this transaction event. This is the sum of the net amount and the fee amount.                                                                                          |
| fee\_amount             | Number (Integer)                                 | The fee associated with this transaction event                                                                                                                                                 |
| fee\_variable           | Number (Integer)                                 | The variable fee associated with this transaction event                                                                                                                                        |
| fee\_fixed              | Number (Integer)                                 | The fixed fee associated with this transaction event                                                                                                                                           |
| currency\_code          | String (ISO 4217 Alpha-3 Currency code)          | Client's configured currency. Amounts use the smallest-denomination unit available in this currency. (for example, amount = 100 for \$1 USD, where the smallest unit is a cent)                |
| settled\_at             | String (datetime using RFC 3339 standard in UTC) | Time at which the ACH transfer that settled this transaction originated                                                                                                                        |

#### CSV Sample

```
merchant_id,merchant_reference_id,settlement_batch_id,payment_id,payment_reference_id,refund_id,refund_reference_id,dispute_id,transaction_type,transaction_time,net_amount,gross_amount,fee_amount,fee_variable,fee_fixed,currency_code,settled_at
MMI_9w89nidchumz9ktrcpnalg2ny,vt9bsxyv0c0xsgwtwrxnsymt7,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,PWC_g74t4d97rr2qg1qe37gpa6bma,payment_reference1,,,,CAPTURE,2021-01-02T10:24:21Z,9700,10000,300,100,200,USD,2021-01-02T23:02:00Z
MMI_9w89nidchumz9ktrcpnalg2ny,vt9bsxyv0c0xsgwtwrxnsymt7,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,PWC_g74t4d97rr2qg1qe37gpa6bma,payment_reference1,PWCR_g74d6d97rr2qg1qe37gpa6bma,refund_reference1,,REFUND,2021-01-02T10:24:21Z,-10000,-10000,0,0,0,USD,2021-01-02T23:02:00Z
MMI_9w89nidchumz9ktrcpnalg2ny,vt9bsxyv0c0xsgwtwrxnsymt7,PWCS_fg2sxvvhg1ff9p4tj1731sdy3,PWC_dmwmsh0zrskryvdthvbm8ddgs,payment_reference2,,,DSPT_jjdbzt6gvkecemz2s6q1cbfp2,CHARGEBACK,2021-01-02T10:24:21Z,-11000,-10000,1000,0,1000,USD,2021-01-02T23:02:00Z
```

## Balance Summary Report

The Balance Summary report contains the client's starting balance and ending balance, activity and payout details for a given processing window—to help understand daily payout, and provide information on carried-forward balances. Each report is given a unique filename to avoid upload collisions using the following convention:
`<yyyymmdd>_balance_summary_report_client_<client-id>_batch_<batch-id>.csv`

<br />

> `<yyyymmdd>` is the date of settlement for the settlement batch.

<br />

### CSV Schema

Each file will contain headers in the top row, and then exactly four rows with the following schema:

| Column Name | Type                                    | Description                                                                                                                                                                                                                                                                                                        |
| :---------- | :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| category    | String                                  | The record category `{`starting\_balance`, `ending\_balance`, `payout`, `activity`}`                                                                                                                                                                                                                               |
| description | String                                  | Description of the record category, as follows: <br />`starting balance`: "Starting Balance ( `ISO 8061 starting date of this settlement batch`)" <br />`ending balance`: "Ending Balance ( `ISO 8061 ending date of this settlement batch`)" <br />`payout`: "Total Payouts" <br />`activity`: "Payment Activity" |
| currency    | String (ISO 4217 Alpha-3 Currency code) | Client's configured currency. Amounts use the smallest-denomination unit available in this currency. (ex. amount = 100 for \$1 USD, where the smallest unit is a cent)                                                                                                                                             |
| net\_amount | Number(Integer)                         | Net amount for the given category.                                                                                                                                                                                                                                                                                 |

#### CSV Sample

```csv
"category","description","currency","net_amount"
"starting_balance","Starting Balance (2021-07-23)","USD","0"
"ending_balance","Ending Balance (2021-07-24)","USD","0"
"payout","Total Payouts","USD","187434"
"activity","Payment Activity","USD","187434"
```

### Negative net settlements

If a given processing window has a negative net settlement, no funds will be delivered to the client and Cash App will carry-forward the negative balance to the following day. The Balance Summary Report will reflect this negative balance as shown below:

#### CSV Sample

```csv
"category","description","currency","net_amount"
"starting_balance","Starting Balance (2023-03-21)","USD","0"
"ending_balance","Ending Balance (2023-03-22)","USD","-26285"
"payout","Total Payouts","USD","0"
"activity","Payment Activity","USD","-26285"
```

## Activity Summary Report

The Activity Summary report contains the net amount, gross amount, and fee amount totals for each transaction category. Each report is given a unique filename to avoid upload collisions using the following convention:
`<yyyymmdd>_activity_summary_report_client_<client-id>_batch_<batch-id>.csv`

<br />

> `<yyyymmdd>` is the date of settlement for the settlement batch.

<br />

### CSV Schema

Each file will contain headers in the top row, and then exactly three rows(one row per transaction type) with the following schema:

| Column Name       | Type                                    | Description                                                                                                                                                            |
| :---------------- | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count             | Number(Integer)                         | Number of transactions processed for this transaction type                                                                                                             |
| currency          | String (ISO 4217 Alpha-3 Currency code) | Client's configured currency. Amounts use the smallest-denomination unit available in this currency. (ex. amount = 100 for \$1 USD, where the smallest unit is a cent) |
| transaction\_type | String                                  | The type of transaction {`CAPTURE`, `REFUND`, `CHARGEBACK`}                                                                                                            |
| gross\_amount     | Number(Integer)                         | The sum of gross amounts of all transactions in this transaction batch                                                                                                 |
| net\_amount       | Number(Integer)                         | The sum of net amounts of all transactions in this transaction batch                                                                                                   |
| fee\_amount       | Number(Integer)                         | The sum of fee amounts of all transactions in this transaction batch                                                                                                   |

#### CSV Sample

```text
"count","currency","transaction_type","gross_amount","net_amount","fee_amount"
"7","USD","CAPTURE","5667","5508","159"
"2","USD","REFUND","1619","1573","45"
"1","USD","CHARGEBACK","809","786","22"
```

> Fraud disputes where Cash App Pay takes on liability are included here for informational purposes only and do not impact settlement.

---

# Refunds

List of topics in this article

* [Refunds](#refunds)

* [Issue a Refund (Authorization)](#refund-authorization)

* [Capture a Refund](#refund-capture)

* [Void a Refund](#void-a-refund)

---

# Refunds

Refunds allow a Merchant/PSP to send funds from a Merchant to a Customer.

Refunds are linked to a previously captured Cash App Pay Payment. They must not have an amount greater than the captured amount on the original Payment. Read more [here](/cash-app-pay-partner-api/guides/resources/frequently-asked-questions/returns-and-refunds)

<Note>
  Cash App has set a maximum time limit of 7 years to issue a refund.
</Note>

<Note>
  Refunds typically process in several business days following initiation, except for Stored Value Balance (SVB) which is immediate. Transaction fees will not be returned to the PSP in the event of a refund.
</Note>

![refunds.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/refunds.png)

## Refund Authorization

Authorizations are valid for and must be captured within 7 days to complete a Refund. Authorizations not captured within 7 days are voided, and a new authorization will be required to complete a Refund.

<Note>
  Refunds can be authorized and captured via a single API call by setting <code>capture=true</code>. See the API reference for more information.
</Note>

### Refund Authorization Failure Scenarios and Error Codes

| Action                                    | Description                                                                                                                                                                             |
| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PAYMENT\_NOT\_FOUND (linked refunds only) | Cash App could not find the Payment to Refund.                                                                                                                                          |
| CUSTOMER\_DISABLED                        | The Cash App account of the Customer receiving the Refund is deactivated.                                                                                                               |
| MERCHANT\_DISABLED                        | Merchant is deactivated in Cash App Pay and cannot issue Refunds.                                                                                                                       |
| MERCHANT\_PENDING                         | Merchant onboarding has not yet completed and the Merchant cannot issue Refunds.                                                                                                        |
| REFUND\_DECLINED\_COMPLIANCE              | Refund is declined by Block for compliance reasons, including violation of Cash App Terms of Service, Program Rules, or applicable laws.                                                |
| REFUND\_DECLINED\_OTHER                   | Refund is declined for an unknown reason.                                                                                                                                               |
| REFUND\_DECLINED\_RISK                    | Refund is declined due to riskiness. Block’s risk models will decline Refunds if they detect potentially fraudulent or otherwise risky activity.                                        |
| REFUND\_INVALID\_AMOUNT\_MISMATCH         | Refund amount did not match the amount shown to the Customer during the Customer Request for Refund.                                                                                    |
| REFUND\_INVALID\_CURRENCY\_MISMATCH       | Refund currency did not match the currency shown to the Customer during the Customer Request for Refund, or the currency of the Merchant did not match the Refund’s currency.           |
| REFUND\_INVALID\_PAYMENT\_UNCAPTURED      | The Payment being refunded has not been captured and therefore cannot be refunded.                                                                                                      |
| REFUND\_INVALID\_TOO\_LARGE               | The requested Refund amount is too high. Cash App Pay’s maximum Refund size may be adjusted to prevent fraud, though this is not equivalent to a risk decline (`REFUND_DECLINED_RISK`). |
| REFUND\_INVALID\_TOO\_SMALL               | The requested Refund amount is too low (below \$0.01 USD).                                                                                                                              |

## Refund Capture

Once a Refund has been authorized, it must be captured within 7 days to complete the Refund and trigger the Settlement process. Only the **exact** amount that was authorized is captured since Refunds should not be over or under-captured.

## Void a Refund

Once a Refund has been authorized but before it has been captured, it can be voided. This cancels the authorization and is a terminal state for the Refund. This is only applicable while the Refund authorization is valid.

<Note>
  If a Refund is not captured seven days after authorization, it will be automatically voided.
</Note>

---

# Sandbox Overview

In the Sandbox environment you can  test your integration without moving any money. These are the Sandbox environments that Cash App Pay provides to you:

* [Sandbox App](/cash-app-pay-partner-api/guides/technical-guides/sandbox/sandbox-app)
* [Developer Sandbox](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox)

---

# Sandbox App

## Overview

The Sandbox App allows our third-party integrators to verify that their API/SDK code is implemented properly.

We created the Sandbox App so that it mimics the Cash App experience without using our existing flows in our Production environment. This keeps our Production environment safer since we do not expose it to external parties. The Production environment will have the latest version of the Cash App that we distribute to our Partners.

Therefore, the Sandbox App is very useful to Partners because they don't have to download and set up Cash App with a Production (i.e., real bank) account. We provide them an experience that is almost identical to what actual users might see inside of Cash App when they use Cash App Pay for payments.

## Benefits of using Sandbox App for testing

These are the benefits of using the Sandbox App for testing:

* It allows for deep-linked testing during development in Sandbox

* It enables development teams outside the US who don't have access to Cash App via the App Store to test a deep-linked end-to-end journey

* Production testing with the actual Cash App should only be completed as a final step after Partner Certification. The Cash App we deliver to our Partners should ONLY ever be used in the Production environment

* Partners do not have to create a Production account just to test their integration

---

# Sandbox App: Testing and Usage

Prerequisites to using the Sandbox app are:

* Partners must have the API credentials, and must have integrated with our API via the Pay Kit SDK

* Once they have integrated with Cash App Pay, they can use the Sandbox App to validate their integration

## Download and Install instructions

Contact the Partner Engineering team or your Cash App Point of Contact to set up the API credentials for your integration and to get the download and install instructions for the Sandbox App (both for Android and iOS).

The download links for the Sandbox App (for both Android and iOS) are as follows:

* **iOS link:** [https://testflight.apple.com/join/TZY8IaM9](https://testflight.apple.com/join/TZY8IaM9)

* **Android link:** [https://appdistribution.firebase.dev/i/fd95262a158a32fd](https://appdistribution.firebase.dev/i/fd95262a158a32fd)

---

# Use Cases

There are currently two Use Cases for the Sandbox App. We recommend that Partners test both these with the Sandbox App. They are:

* **Desktop:** Scan a QR code from the Merchant's website on a desktop by loading a QR code via the Pay Kit SDK

* **Mobile:** Install the Sandbox App in a mobile device. Using the mobile device's browser, navigate to the Merchant's website and click on the **Pay Kit** button. This should deep link them into the Sandbox App. Mobile has the option for both Android and iOS

## Use Case 1: Scan QR code using the in-app scanner

1 On Desktop, navigate to our [Sandbox testing](https://sandbox.pay.withcash.app/checkout) store. Click on the **Cash App Pay** button. This displays the QR code.

![Sandbox test store](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/sandbox-test-store.png)

![Sandbox test store QR code](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/sandbox-test-store-qr-code.png)

2 Open the Sandbox App and tap the **Open Scanner** button.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/sandbox-app-qr-scanner.png" alt="Sandbox app QR scanner" />

3 Scan the QR code on the Desktop using the Sandbox App.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/sandbox-scan-desktop-qr.png" alt="Scan sandbox desktop QR code" />

<Note>You can use the native camera on mobile device to scan the QR code on the Desktop. Tapping on the link from the QR code scan will deep link you to the Sandbox app. There may be slight variations in the deep linking based on the native camera app that you use. For example, you may have to click on a link to go to the Sandbox app.</Note>
4 **Approve** the payment in the Sandbox App.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/approve-payment.png" alt="Approve payment" />

<Note>You can also **Decline** the payment and the Sandbox App will ask you to go back to the Sandbox testing store.</Note>
5 You can see Cash App Pay has confirmed the payment by displaying the amount.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/order-confirmation.png" alt="Order confirmation" />

6 Observe the linked account. `$CASHTAG_C_TOKEN` is our fake account used inside the Sandbox.

![Cashtag token](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/cashtag-token.png)

## Use Case 2: Scan QR codes using a mobile device camera

1 On mobile, navigate to our [Sandbox testing](https://sandbox.pay.withcash.app/checkout). Click on the **Cash App Pay** button.

![Sandbox test store](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/sandbox-test-store.png)

2 You are redirected back to the Sandbox App. **Approve** the payment in the Sandbox App.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/approve-payment.png" alt="Approve payment" />

3 You can see Cash App Pay has confirmed the payment by displaying the amount.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/order-confirmation.png" alt="Order confirmation" />

4 Observe the linked account. `$CASHTAG_C_TOKEN` is our fake account used inside the Sandbox.

![Cashtag token](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/cashtag-token.png)

<Note>
  You can also **Decline** the payment and the Sandbox App will ask you to go back to the shopping website.
</Note>

## Use Case 3: Testing Payment Errors in the Sandbox App

1 On mobile, navigate to our [Sandbox testing](https://sandbox.pay.withcash.app/checkout). Click on the **Cash App Pay** button.

![Sandbox test store](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/sandbox-test-store.png)

2 You are redirected back to the Sandbox App. Click **View more options** in the Sandbox App.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/cap-sand-view-more-opts.jpeg" alt="cap-sand-view-more-opts.jpeg" />

3 The first of several test options appear, in the picture below they are *Account Ineligibilty Overrides* **Customer Ineligible**, and *Payment Overrides* **Connection Error** and **Compliance**.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/2.PNG" alt="2.PNG" />

4 Scroll down for more test options. In the picture below there are two more *Payment Overrides* **Insufficient Funds** and **Other**.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/3.PNG" alt="3.PNG" />

5 Scroll down for final set of test options. In the picture below there are three more *Payment Overrides* **Risk**, **Too Large** and **Too Small**.

6 See the *Magic Values* table in the [Developer Sandbox page](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox#magic-values) for details about testing these payment errors.

---

# FAQs

**Who is the main audience for this app?**

The main audience for this app is the developers of the businesses to whom we give the Cash App Pay API credentials. We will also give them the links to the Sandbox apps (both Android and iOS).

**Is the Sandbox app widely available for external users?**

No. the App is not widely available for external users.

**Can we use it on Desktop?**

You need a Desktop to test the Pay Kit web SDK. The Pay Kit SDK loads the Merchant website which displays the QR code you have to scan using the Sandbox App. We may consider building a special version of the Sandbox iOS for desktop simulators.

**Is there a difference between the iOS and Android app?**

There are no functional differences between the Android and iOS apps, as the apps are written using a single codebase.

---

# Developer Sandbox

Cash App provides a sandbox environment for developers to test integrations without moving money. This environment can be reached by using the sandbox.api.cash.app host.

This environment has a separate set of credentials from production.

The sandbox can be controlled through magic values (documented below) in order to produce certain behaviors. In other cases, API responses will represent successful actions when given valid requests.

<Note>
  We have a 5-year full backwards compatibilty guarantee that extends to our publicly documented Sandbox Magic Values listed on this page.
</Note>

## Magic Values

### [Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)

| Field        | Value                 | Result                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------ | --------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount       | 6670                  | Connection Error                               | The payment will be created but the response will be an HTTP error. This simulates potential network failures.<br /><br />The state of the payment can be retrieved using [retrieve payment](/cash-app-pay-partner-api/api-reference/network-api/retrieve-payment). <br /><br />The request can also be  voided through the [void payment](/cash-app-pay-partner-api/api-reference/network-api/void-payment) endpoint |
| amount       | 7770                  | Payment decline: compliance failure            | The payment will be created in a declined state, with the reason PAYMENT\_DECLINED\_COMPLIANCE                                                                                                                                                                                                                                                                                                                        |
| amount       | 7771                  | Payment decline: insufficient funds            | The payment will be created in a declined state, with the reason PAYMENT\_DECLINED\_INSUFFICIENT\_FUNDS                                                                                                                                                                                                                                                                                                               |
| amount       | 7772                  | Payment decline: other                         | The payment will be created in a declined state, with the reason PAYMENT\_DECLINED\_OTHER                                                                                                                                                                                                                                                                                                                             |
| amount       | 7773                  | Payment decline: risk                          | The payment will be created in a declined state, with the reason PAYMENT\_DECLINED\_RISK                                                                                                                                                                                                                                                                                                                              |
| amount       | 7774                  | Payment decline: too large                     | The payment will be created in a declined state, with the reason PAYMENT\_INVALID\_TOO\_LARGE                                                                                                                                                                                                                                                                                                                         |
| amount       | 7775                  | Payment decline: too small                     | The payment will be created in a declined state, with the reason PAYMENT\_INVALID\_TOO\_SMALL                                                                                                                                                                                                                                                                                                                         |
| merchant\_id | MMI\_sandbox:disabled | Payment creation failure: merchant is disabled | The payment will not be created, returning an error of MERCHANT\_DISABLED.                                                                                                                                                                                                                                                                                                                                            |
| merchant\_id | MMI\_sandbox:pending  | Payment creation failure: merchant is pending  | The payment will not be created, returning an error of MERCHANT\_PENDING                                                                                                                                                                                                                                                                                                                                              |
| merchant\_id | MMI\_sandbox:missing  | Payment creation failure: merchant is missing  | The payment will not be created, returning an error of MERCHANT\_NOT\_FOUND                                                                                                                                                                                                                                                                                                                                           |
| grant\_id    | GRG\_sandbox:active   | Payment created                                | The payment will be created.                                                                                                                                                                                                                                                                                                                                                                                          |
| grant\_id    | GRG\_sandbox:consumed | Payment decline: grant error                   | The payment will be created in a declined state, with the reason GRANT\_CONSUMED                                                                                                                                                                                                                                                                                                                                      |
| grant\_id    | GRG\_sandbox:expired  | Payment decline: grant error                   | The payment will be created in a declined state, with the reason GRANT\_EXPIRED                                                                                                                                                                                                                                                                                                                                       |
| grant\_id    | GRG\_sandbox:missing  | Payment decline: grant error                   | The payment will be created in a declined state, with the reason GRANT\_NOT\_FOUND                                                                                                                                                                                                                                                                                                                                    |
| grant\_id    | GRG\_sandbox:revoked  | Payment decline: grant error                   | The payment will be created in a declined state, with the reason GRANT\_REVOKED                                                                                                                                                                                                                                                                                                                                       |
| amount       | 8801                  | Create dispute: `CD10`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `CD10`<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                 |
| amount       | 8802                  | Create dispute: `CD11`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `CD11`<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                 |
| amount       | 8803                  | Create dispute: `CD12`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `CD12`. <br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                               |
| amount       | 8804                  | Create dispute: `CD13`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `CD13` <br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                |
| amount       | 8811                  | Create dispute: `FR10`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `FR10` <br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                |
| amount       | 8812                  | Create dispute: `FR11`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `FR11`<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                 |
| amount       | 8821                  | Create dispute: `PE10`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `PE10`<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                 |
| amount       | 8822                  | Create dispute: `PE11`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `PE11`<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                 |
| amount       | 8823                  | Create dispute: `PE12`                         | The payment will be created along with a dispute that has a disputed amount equal to the transaction amount and a reason of `PE12`<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                 |
| amount       | 8901                  | Create dispute: differing disputed amount      | The payment will be created along with a dispute that has a disputed amount different from the payment amount<br /><br />The dispute can be queried through the [List Disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes) API two seconds after the payment is created.                                                                                                                      |

### [Create refund](/cash-app-pay-partner-api/api-reference/network-api/create-refund)

| Field     | Value                 | Result                         | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------- | --------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount    | 6670                  | Connection Error               | The refund will be created but the response will be an HTTP error. This simulates potential network failures.<br /><br />The state of the refund can be retrieved using [retrieve refund](/cash-app-pay-partner-api/api-reference/network-api/retrieve-refund). <br /><br />The request can also be  voided through the [void refund](/cash-app-pay-partner-api/api-reference/network-api/void-refund) endpoint |
| amount    | 7770                  | Refund decline: compliance     | The refund will be created in a declined state, with the reason REFUND\_DECLINED\_COMPLIANCE                                                                                                                                                                                                                                                                                                                    |
| amount    | 7772                  | Refund decline: other          | The refund will be created in a declined state, with the reason REFUND\_DECLINED\_OTHER                                                                                                                                                                                                                                                                                                                         |
| amount    | 7773                  | Refund decline: risk           | The refund will be created in a declined state, with the reason REFUND\_DECLINED\_RISK                                                                                                                                                                                                                                                                                                                          |
| amount    | 7774                  | Refund decline: too large      | The refund will be created in a declined state, with the reason REFUND\_DECLINED\_TOO\_LARGE                                                                                                                                                                                                                                                                                                                    |
| amount    | 7775                  | Refund decline: too small      | The refund will be created in a declined state, with the reason REFUND\_DECLINED\_TOO\_SMALL                                                                                                                                                                                                                                                                                                                    |
| amount    |                       |                                |                                                                                                                                                                                                                                                                                                                                                                                                                 |
| grant\_id | GRG\_sandbox:consumed | Refund failure: grant consumed | The refund will be created in a declined state, with the reason GRANT\_CONSUMED                                                                                                                                                                                                                                                                                                                                 |
| grant\_id | GRG\_sandbox:expired  | Refund failure: grant expired  | The refund will be created in a declined state, with the reason GRANT\_EXPIRED                                                                                                                                                                                                                                                                                                                                  |
| grant\_id | GRG\_sandbox:missing  | Refund failure: grant missing  | The refund will be created in a declined state, with the reason GRANT\_NOT\_FOUND                                                                                                                                                                                                                                                                                                                               |
| grant\_id | GRG\_sandbox:revoked  | Refund failure: grant revoked  | The refund will be created in a declined state, with the reason GRANT\_REVOKED                                                                                                                                                                                                                                                                                                                                  |

### Create [file-](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file) or [text-](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-text) based dispute evidence

| Field    | Value                                            | Result         | Description                          |
| -------- | ------------------------------------------------ | -------------- | ------------------------------------ |
| metadata | `{"sandbox:set_dispute_state": "PROCESSING"}`    | PROCESSING     | Dispute adjudicated: `PROCESSING`    |
| metadata | `{"sandbox:set_dispute_state": "WON"}`           | WON            | Dispute adjudicated: `WON`           |
| metadata | `{"sandbox:set_dispute_state": "PARTIALLY_WON"}` | PARTIALLY\_WON | Dispute adjudicated: `PARTIALLY_WON` |
| metadata | `{"sandbox:set_dispute_state": "LOST"}`          | LOST           | Dispute adjudicated: `LOST`          |

### API Key (Signed) Requests

| Header      | Value                        | Result                  | Description                                                      |
| ----------- | ---------------------------- | ----------------------- | ---------------------------------------------------------------- |
| X-Signature | sandbox:skip-signature-check | valid request signature | The request will be treated as if it contains a valid signature. |

---

# Postman Collection

You can use Cash App Pay's Postman collection to test the APIs in Sandbox and Production.

## What is Postman?

[Postman](https://www.postman.com/) is a free-to-download tool for making HTTP requests.

## Download Postman

1. Visit the [Postman website](https://www.postman.com/) and download the version of Postman required for your platform.
2. Install the **Postman** application on your computer.

## Cash App Pay Postman collections

<Note>
  Download these files to your computer/local drive:

  * [Cash App Pay Postman Collection](https://cash-f.squarecdn.com/static/CAP_Postman_Collection.json)

  * [Cash App Pay Environment Variables](https://cash-f.squarecdn.com/static/CAP_Environment_Variables.json)
</Note>

<Note>
  These files are valid for United States *only*.
</Note>

<Note>
  Environment variables are using the Sandbox base url. To test in Production, you can update the `host` to the production base url `api.cash.app`
</Note>

## Import to Postman

To import the Cash App Pay Postman collection to the **Postman** application on your computer, do the following:

1. Open the **Postman** application on your computer.
2. Click **Import**.
3. Select the Cash App Pay Postman collection files that you want to import.
   <Tip> You can also import the entire collection by pasting the url of the json file. </Tip>
4. Once the files are successfully imported, you can start to test out the Cash App Pay APIs on Postman.

---

# Changelog Details

<Note>
   Android and iOS SDK changelogs are found in GitHub. See changelogs here: 

  <br />

  [Android SDK](https://github.com/cashapp/cash-app-pay-android-sdk/blob/main/CHANGELOG.md)

   

  <br />

  [iOS SDK](https://github.com/squareup/cash-app-pay-sdk-ios/blob/main/RELEASE-NOTES.md)

   
</Note>

---

# Changelog Details

Find all the API changelogs listed below:

<Note>
   The changelogs are listed from newest to oldest (in ascending order) 
</Note>

***

## Added `statement_descriptor` field to `enrichments` when creating a payment

Date: Feb-10-2025
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

[Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)

Description:

**Description:** In the Network API `Create payment`, we have added a new optional `statement_descriptor` field to the `enrichments` sub-resource within the payment resource. This field allows a merchant, via their Payment Service Provider, to add a descriptor for the payment, which will then be reflected in-app within a customer's Activity page.

If the input for this field exceeds the character limit, it will be truncated to the limit, then suffixed with an ellipsis (...).

***

## Added `PAYMENT_DECLINED_CUSTOMER_BLOCKED_BY_MERCHANT` failure code

Date: Apr-15-2025
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

[Create payment authorization](/cash-app-pay-partner-api/api-reference/network-api/create-payment-authorization)

**Description:**

A new standalone error code has been added to payment authorizations, `PAYMENT_DECLINED_CUSTOMER_BLOCKED_BY_MERCHANT`, to indicate that a payment was declined because the customer has blocked the merchant. This error code is returned when a payment is declined due to  a customer-initiated block.

***

## Added `Create payment authorization` endpoint

Date: Feb-28-2025
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

[Create payment authorization](/cash-app-pay-partner-api/api-reference/network-api/create-payment-authorization)

**Description:**

The new Network API `Create payment authorization` enables incremental authorization on previously created payments. Instead of overcapturing, developers can request an additional authorization for an increased amount without putting at risk the original authorization.

Additionally, this adds an optional `authorization_updates` field on all `Payment` schemas that may exist in API responses. This field will contain only incremental authorization updates, and not the authorization from the original request.

***

## Add `initiation` field to `enrichments` when creating a payment

Date: Feb-10-2025
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

[Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)

Description:

**Description:** In the Network API `Create payment`, we have added a new optional `initiation` field to the enrichment sub-resource, within the payment resource that contains information about who initiated a transaction. There is currently one property within this field: `actor`, which can be one of the following values:

* `CUSTOMER`: describe the payment as a customer initiated transaction
* `MERCHANT`: describe the payment as a merchant initiated transaction

***

## Reject requests uploading empty evidence files

Date: Jul-02-2024
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

[Create dispute evidence file](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file)

**Description:**

Fail requests to create a dispute evidence file if the file is empty.

***

## Added `List customer grants` endpoint

Date: Jan-31-2024
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

[List customer grants](/cash-app-pay-partner-api/api-reference/network-api/list-customer-grants)

**Description:**

Developers can now retrieve all grants for a customer.

***

## Created alternative signature for multipart/form-data requests

Date: Jan-19-2024
<br />Changelog Type: Improved
<br />Metadata Tag: Network API

**Affected endpoints:**

[Create dispute evidence file](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file)

**Description:**

Computing a valid request signature for `multipart/form-data` requests is challenging. A [new signing algorithm](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/requests/signing-requests) for multipart requests is supported that includes an alternative signature in the request body, rather than the existing `X-Signature` header.

***

## Improved Grant flow back navigation update

Date: Dec-15-2023
<br />Changelog Type: Improved
<br />Metadata Tag: Grant Flow

**Description:**

When a customer initiates the Cash App customer registration process, they are deeplinked from the merchant checkout page into Cash App where they are authenticated via the grant flow and then subsequently redirected back to the merchant checkout page.

The mechanism to automatically redirect back to the merchant checkout page after the grant flow was retired in iOS 17; therefore, a new screen has been added to the grant flow which explicitly guides the customer to backward redirect via a button on the top left corner. If the customer doesn’t complete the backward redirect action, they will be prompted to forward redirect back to the merchant checkout page via a separate button within the grant screen.

As before, developers are expected to handle both forward navigation and backward navigation scenarios after the grant flow has been completed.

***

## Fixed stale customer request after grant is revoked

Date: Dec-15-2023 (select partners)
<br />Changelog Type: Improved
<br />Metadata Tag: Customer Request API

**Affected endpoints:**

[Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)

**Description:**

An approved customer request contains grants that can be used to perform actions specified in the request using the Network API. Previously if a grant was consumed or revoked post customer request approval, the Customer Request API would return stale data - the used grant would appear as active even though the grant was consumed or revoked.

With this fix, the Customer Request API will always return the most up-to-date grant status if the customer request is retrievable.

As a reminder, the [Retrieve Customer Grant](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer-grant) endpoint within the Network API will always return the most up-to-date grant status.

***

## Fixed documentation for activity reconciliation report files

Date: Dec-08-2023
<br />Changelog Type: Improved
<br />Metadata Tag: Settlement

**Description:** We removed date ranges from the specifications of the activity reconciliation report file names as generating activity reconciliation reports for a date range is not supported.
We also added clarifications around the semantics of the yyMMdd date prefix in the activity reconciliation report file name.

***

## Improved Grant flow idle detection

Date: Oct-18-2023
<br />Changelog Type: Improved
<br />Metadata Tag: Grant Flow

**Affected endpoints:**

[Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)

**Description:**

During customer registration, the customer may be prompted to complete a subsequent action before the flow is approved and a grant is generated. If the flow is not actioned upon after a specified TTL, the customer request will transition to a `DECLINED` status.

Previously, the customer request would remain in a `PROCESSING` status until the customer request expired.

With this change, developers will have a more straightforward customer request lifecycle where customer requests will reach a terminal status and be declined more quickly when a customer fails to complete the grant flow before the customer request expires.

Because customer request status can be updated without a subsequent redirect back to the merchant checkout page, developers should ensure that they can properly react to a customer request status change with or without a redirect occurring (Pay Kit handles this scenario automatically).

***

## Improved Sandbox App magic value support

Date: Oct-5-2023
<br />Changelog Type: Improved
<br />Metadata Tag: Sandbox

**Description:**
Previously, developers were required to use these [magic values](/cash-app-pay-partner-api/guides/technical-guides/sandbox/developer-sandbox#magic-values) with the [Create Payment API](/cash-app-pay-partner-api/api-reference/network-api/create-payment) to produce certain behaviors within the Cash App Developer Sandbox.

Now, developers can use the Sandbox App to simulate certain behaviors such as payment declined compliance, payment declined insufficient funds, payment declined other, payment declined risk, payment invalid too large, and payment invalid too small.

***

## Added `capture_before` field to payment resource

Date: Oct-04-2023
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

* [Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)
* [Void payment](/cash-app-pay-partner-api/api-reference/network-api/void-payment)
* [Capture payment](/cash-app-pay-partner-api/api-reference/network-api/capture-payment)
* [List payments](/cash-app-pay-partner-api/api-reference/network-api/list-payments)
* [Retrieve payment](/cash-app-pay-partner-api/api-reference/network-api/retrieve-payment)
* [Void payment by idempotency key](/cash-app-pay-partner-api/api-reference/network-api/void-payment-by-idempotency-key)

**Description:** In the Network API, we have added a new `capture_before` field to the payment resource that designates when created payments should be captured by.

***

## Improved Payment Authorization Failure Codes

Date: Sep-19-2023
<br />Changelog Type: Improved
<br />Metadata Tag: Network API

**Affected endpoints:**

* [Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)

**Description:**

Improvements have been made to return a more specific payment authorization failure code when a Cash App Pay payment authorization failure occurs.

More specifically, payments that previously were coded with the `PAYMENT_DECLINED_OTHER` error code have been updated to reflect a more accurate error code such as `PAYMENT_DECLINED_RISK`, `PAYMENT_DECLINED_COMPLIANCE` and `PAYMENT_DECLINED_LIMIT_REACHED`.

***

## Added `Create request chain` endpoint

Date: Aug-4-2023
<br />Changelog Type: Added
<br />Metadata Tag: Management API

**Affected endpoints:**

* [Create request chain](/cash-app-pay-partner-api/api-reference/management-api/create-request-chain)

**Description:**

Clients can improve their performance by implementing request chaining into their integration. For more information, see [Optimizing Performance with Request Chaining](/cash-app-pay-partner-api/guides/technical-guides/integrating-with-cash-app-pay/optimizing-performance-with-request-chaining).

***

## Added `FEE_PLANS_READ` scope to Create API Key’s scope

Date: July-13-2023
<br />Changelog Type: Added
<br />Metadata Tag: Management API

**Affected endpoints:**

* [Create API Key](/cash-app-pay-partner-api/api-reference/management-api/create-api-key)

**Description:**

When creating API keys, clients may add the `FEE_PLANS_READ` scope in order to retrieve their fee plans.

***

## Added `customer.deleted` webhook event

Date: May-30-2023
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

* [RetrieveCustomer](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer)

**Description:**

When a Cash App customer account is deleted, the `customer.deleted` webhook event is delivered with the relevant customer information. Any attempt to retrieve this customer via `RetrieveCustomer` will return the new `CUSTOMER_DELETED_ACCOUNT` error.

***

## Fixed nesting of `object` property of all webhook event schema

Date: May-23-2023
<br />Changelog Type: Fixed
<br />Metadata Tag: Management API, Customer Request API

**Affected webhook events**

* [Event: grant.created](/cash-app-pay-partner-api/api-reference/network-api/grant-created)
* [Event: grant.status.updated](/cash-app-pay-partner-api/api-reference/network-api/grant-status-updated)
* [Event: customer.created](/cash-app-pay-partner-api/api-reference/network-api/customer-created)
* [Event: customer.updated](/cash-app-pay-partner-api/api-reference/network-api/customer-updated)
* [Event: dispute.created](/cash-app-pay-partner-api/api-reference/network-api/dispute-created)
* [Event: dispute.status.updated](/cash-app-pay-partner-api/api-reference/network-api/dispute-status-updated)
* [Event: merchant.status.updated](/cash-app-pay-partner-api/api-reference/network-api/merchant-status-updated)
* [Event: payment.status.updated](/cash-app-pay-partner-api/api-reference/network-api/payment-status-updated)
* [Event: refund.status.updated](/cash-app-pay-partner-api/api-reference/network-api/refund-status-updated)
* [Event: customer\_request.state.updated](/cash-app-pay-partner-api/api-reference/customer-request-api/customer-request-state-updated)

**Description:**

The webhook event schemas now include an additional layer of nesting under the `object` property.

***

## Updated map validation errors

Date: May-15-2023
<br />Changelog Type: Fixed
<br />Metadata Tag: Network API, Customer Request API

**Affected endpoints:**

* [Create brand](/cash-app-pay-partner-api/api-reference/network-api/create-brand)
* [Update brand](/cash-app-pay-partner-api/api-reference/network-api/update-brand)
* [Upsert brand](/cash-app-pay-partner-api/api-reference/network-api/upsert-brand)
* [Create dispute evidence (text)](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-text)
* [Create dispute evidence (file)](/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file)
* [Create merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant)
* [Update merchant](/cash-app-pay-partner-api/api-reference/network-api/update-merchant)
* [Upsert merchant](/cash-app-pay-partner-api/api-reference/network-api/upsert-merchant)
* [Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)
* [Create refund](/cash-app-pay-partner-api/api-reference/network-api/create-refund)
* [Create request](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request)
* [Update request](/cash-app-pay-partner-api/api-reference/customer-request-api/update-request)

**Description:**

In the Network API and Customer Request API, when the `metadata` field is constructed with too few or too many elements, error codes will be returned. Previously these error codes were: `ARRAY_LENGTH_TOO_SHORT` and `ARRAY_LENGTH_TOO_LONG`. But now, we have changed them to:   `TOO_FEW_MAP_ELEMENTS` and `TOO_MANY_MAP_ELEMENTS`.

***

## Added new fee plan API endpoints

Date: Mar-08-2023
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

* [List fee plans](/cash-app-pay-partner-api/api-reference/network-api/list-fee-plans)
* [Retrieve fee plan](/cash-app-pay-partner-api/api-reference/network-api/retrieve-fee-plan)
* [List merchants](/cash-app-pay-partner-api/api-reference/network-api/list-merchants)
* [Create merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant)
* [Upsert merchant](/cash-app-pay-partner-api/api-reference/network-api/upsert-merchant)
* [Retrieve merchant](/cash-app-pay-partner-api/api-reference/network-api/retrieve-merchant)
* [Update merchant](/cash-app-pay-partner-api/api-reference/network-api/update-merchant)
* [List payments](/cash-app-pay-partner-api/api-reference/network-api/list-payments)
* [Create payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment)
* [Retrieve payment](/cash-app-pay-partner-api/api-reference/network-api/retrieve-payment)
* [Capture payment](/cash-app-pay-partner-api/api-reference/network-api/capture-payment)
* [Void payment](/cash-app-pay-partner-api/api-reference/network-api/void-payment)
* [Void payment](/cash-app-pay-partner-api/api-reference/network-api/void-refund-by-idempotency-key)

**Description:**

In the Network API, merchants can now be created/updated to use default fee plans for in-app, in-person, and/or online payments. The fee information used for each payment will be available in the payment APIs as the `fee_rate` and `fee_amount`.

You can find details on the currently applied fee plan by using the new fee plans APIs [List fee plans](/cash-app-pay-partner-api/api-reference/network-api/list-fee-plans)

* [Retrieve fee plan](/cash-app-pay-partner-api/api-reference/network-api/retrieve-fee-plan).

***

## Status field added to the WebhookEndpoint response

Date: Jan-09-2023
<br />Changelog Type: Added
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [List webhook endpoints](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-endpoints)
* [Create webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint)
* [Retrieve webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/retrieve-webhook-endpoint)
* [Update webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint)

**Description:**

In the Management API,`WebhookEndpoint` responses now include the approval status of a webhook endpoint. Once a webhook endpoint is approved, Cash App will deliver events to that webhook endpoint.

***

## Customer added as a possible type for WebhookEvent EventData

Date: Nov-29-2022
<br />Changelog Type: Added
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [List webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events)

**Description:**

<br />

In the Management API, we will now emit the customer events, `customer.created` and `customer.updated`, with the type `customer`.

***

## Documentation for the X-Signature and X-Region header parameters

Date: Nov-29-2022
<br />Changelog Type: Added
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [List webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events)

**Description:**
In the Management API, the `X-Signature` and `X-Region` header parameters on the `List Webhook Events` endpoint were previously undocumented and we documented them.

***

## Webhook Endpoints default delivery\_timeout and maximum delivery\_timeout updated

Date: Nov-02-2022
<br />Changelog Type: Improved
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [Create webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint)
* [Update webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint)

**Description:**
In the Management API, we updated the default `delivery_timeout` of Webhook Endpoints from 30s to 5s and the maximum `delivery_timeout` from 30s to 10s.

***

## Documentation for the Upsert Merchant and Update Merchant endpoints

Date: Nov-01-2022
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

* [Upsert Merchant](/cash-app-pay-partner-api/api-reference/network-api/upsert-merchant)
* [Update Merchant](/cash-app-pay-partner-api/api-reference/network-api/update-merchant)

**Description:**
In the Network API, the `metadata` request parameter for the `Upsert Merchant` and `Update Merchant` endpoints was previously undocumented and we added new documentation for it.

***

## New customer request channel for native mobile applications

Date: Oct-31-2022
<br />Changelog Type: Added
<br />Metadata Tag: Customer Request API

**Affected endpoints:**

* [Create request](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request)
* [Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)
* [Update request](/cash-app-pay-partner-api/api-reference/customer-request-api/update-request)

**Description:** In the Customer Request API, when creating new customer requests, a new channel, `IN_APP`, can be specified if the customer scans a QR code or is redirected to Cash App from a native mobile application.

***

## Documentation for customer\_metadata

Date: Oct-31-2022
<br />Changelog Type: Added
<br />Metadata Tag: Customer Request API

**Affected endpoints:**

* [Create request](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request)
* [Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)
* [Update request](/cash-app-pay-partner-api/api-reference/customer-request-api/update-request)

**Description:** In the Customer Request API, we added missing documentation about `customer_metadata` to the following:

* `Request response` object that included a `customer_metadata` attribute
* `Create request` endpoint that accepted the `request.customer_metadata` attribute

***

## Documentation of 404 responses for Retrieve Refund and Capture Refund operations

Date: Oct-31-2022
<br />Changelog Type: Improved
<br />Metadata Tag: Network API

**Affected endpoints:**

* [Retrieve refund](/cash-app-pay-partner-api/api-reference/network-api/retrieve-refund)
* [Capture refund](/cash-app-pay-partner-api/api-reference/network-api/capture-refund)

**Description:** In the Network API, the 404 responses for `Retrieve Refund` and `Capture Refund` are now correctly documented as `ErrorResponse` objects. The responses were previously documented as generic objects.

***

## Forward redirect a declined Grant to CUSTOMER\_REQUEST\_DECLINED event not firing

Date: Oct-13-2022
<br />Changelog Type: Fixed
<br />Metadata Tag: Pay Kit SDK

**Description:** In Pay Kit SDK, we fixed the error where a forward redirect from a declined Grant of the `CUSTOMER_REQUEST_DECLINED` event was not firing. We now consistently send the `CUSTOMER_REQUEST_DECLINED` event.

***

## Updated the description of Delete webhook endpoint

Date: Aug-17-2022
<br />Changelog Type: Improved
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [Delete webhook](/cash-app-pay-partner-api/api-reference/management-api/delete-webhook-endpoint)

**Description:** Updated the description of the `Delete webhook` endpoint to add: “**Note:** Events that are created before the webhook endpoint was deleted will still be delivered after the webhook endpoint gets deleted”

***

## Renamed field on the Retrieve Customer endpoint response

Date: Aug-17-2022
<br />Changelog Type: Improved
<br />Metadata Tag: Network API

**Affected endpoints:**

* [Retrieve customer](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer)

**Description:** Renamed the `customer_reference_id` field to `reference_id` on the `Customer` object on the response body of the `Retrieve Customer` endpoint.

***

## URL field of webhook endpoints are now nullable

Date: Aug-17-2022
<br />Changelog Type: Improved
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [Create webhook](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint)
* [Update webhook](/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint)

**Description:** The `url` field of the `request.webhook_endpoint` object has been changed to be nullable. This allows developers to subscribe to webhook events without needing a destination. The [list webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events) operation can be used to poll for webhook events instead.

***

## Webhooks operations in the Management API

Date: Aug-17-2022
<br />Changelog Type: Added
<br />Metadata Tag: Management API, Webhook

**Affected endpoints:**

* [List webhook endpoints](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-endpoints)
* [Create webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint)
* [Retrieve webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/retrieve-webhook-endpoint)
* [Update webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint)
* [Delete webhook endpoint](/cash-app-pay-partner-api/api-reference/management-api/delete-webhook-endpoint)
* [List webhook events](/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events)

**Description:** Added webhooks operations in the Management API to allow developers to manage their webhook endpoints and events.

***

## Customer credited amount for Disputes

Date: Aug-11-2022
<br />Changelog Type: Added
<br />Metadata Tag: Network API

**Affected endpoints:**

* [List disputes](/cash-app-pay-partner-api/api-reference/network-api/list-disputes)
* [Retrieve dispute](/cash-app-pay-partner-api/api-reference/network-api/retrieve-dispute)
* [Challenge dispute](/cash-app-pay-partner-api/api-reference/network-api/challenge-dispute)
* [Accept dispute](/cash-app-pay-partner-api/api-reference/network-api/accept-dispute)

**Description:** Added `customer_credited_amount` to the `dispute` object on the response body of the affected endpoints. `customer_credited_amount` shows the amount credited to the Customer after resolving the dispute.

<Note>
   The amount will be in the lowest denomination of the currency used on the associated payment. 
</Note>

***

## SVG QR Codes for Customer Requests

Date: Aug-10-2022
<br />Changelog Type: Added
<br />Metadata Tag: Customer Request API

**Affected endpoints:**

* [Create request](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request)
* [Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)
* [Update request](/cash-app-pay-partner-api/api-reference/customer-request-api/update-request)

**Description:** Added `qr_code_svg_url` to the `request.auth_flow_triggers` object on the response body of the affected endpoints. This field contains a link to the QR code that launches the customer request flow in Cash App when scanned, encoded as an SVG file. Additionally, the `qr_code_image_url` field is now guaranteed to return a URL that links to a PNG file.

***

## Channel for Grants

Date: Jun-30-2022
<br />Changelog Type: Added
<br />Metadata Tag: Customer Request API, Network API

**Affected endpoints:**

* [Retrieve request](/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request)
* [Retrieve customer grant](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer-grant)
* [Revoke customer grant](/cash-app-pay-partner-api/api-reference/network-api/revoke-customer-grant)

**Description:** Added `channel` to the `request.grants[]` object on the response body of the affected request endpoints; added `channel` to the `grant` object on the response body of the affected grant endpoints. This field contains the value of the channel set on the customer request that was approved to create the grant.

---

# Cash App Pay Assets

Use these assets across any Cash App Pay marketing communications.

We have produced a detailed online presentation called [Cash App Pay Merchant guidelines](https://www.figma.com/deck/AdYz1vJrw1EtludeKHVYQq/Cash-App-Pay-%E2%80%93-Merchant-Guidelines?node-id=2-13270\&viewport=-14%2C-62%2C0.42\&t=9Y6drOfZZiEahWxQ-1\&scaling=min-zoom\&content-scaling=fixed\&page-id=0%3A1). It contains extensive information and advice on assets, themes, customer experience, payment choices and more. View it and then apply its guidelines to use the assets on this page effectively.

<Info>
  Make sure you use the provided link or code sample. The previews shown here are not high resolution images and may appear pixelated if embedded on your site(s). More code samples coming soon!
</Info>

## Logos

### Logo Lockup

| Green White                                                                                                                           | Green Black                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Logo_White.png" alt="$Pay_Logo_White.png" noZoom />                                              | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Logo_Black.png" alt="$Pay_Logo_Black.png" noZoom />                                              |
| `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapppay-color-white-32.svg" height="32" />` | `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapppay-color-black-32.svg" height="32" />` |

<br />

| Mono White                                                                                                                           | Mono Black                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Logo_MonoWhite.png" alt="$Pay_Logo_MonoWhite.png" noZoom />                                         | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Logo_MonoBlack.png" alt="$Pay_Logo_MonoBlack.png" noZoom />                                         |
| `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapppay-mono-white-32.svg" height="32" />` | `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapppay-mono-black-32.svg" height="32" />` |

### Alternative Logo Lockup

| Green White                                                                                                                        | Green Black                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Cash App - Logo Green White.png" alt="Cash App - Logo Green White.png" noZoom />                               | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Cash App - Logo Green Black.png" alt="Cash App - Logo Green Black.png" noZoom />                               |
| `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapp-color-white-32.svg" height="32" />` | `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapp-color-black-32.svg" height="32" />` |

<br />

| Mono White                                                                                                                        | Mono Black                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Cash App - Logo White.png" alt="Cash App - Logo White.png" noZoom />                                    | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Cash App - Logo Black.png" alt="Cash App - Logo Black.png" noZoom />                                    |
| `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapp-mono-white-32.svg" height="32" />` | `<img alt="Cash App" src="https://static.afterpaycdn.com/en-US/integration/logo/lockup/cashapp-mono-black-32.svg" height="32" />` |

### Payment Badge

#### Rounded

| Green On Dark                                                                                                       | Green                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Payment Badge - Green on dark.png" alt="Payment Badge - Green on dark.png" noZoom />              | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Payment Badge - Green.png" alt="Payment Badge - Green.png" noZoom />                      |
| `<img alt="Cash App Pay" src="https://static.afterpaycdn.com/en-US/integration/logo/icon/color.svg" height="24" />` | `<img alt="Cash App Pay" src="https://static.afterpaycdn.com/en-US/integration/logo/icon/color.svg" height="24" />` |

<br />

| Monochrome Black On Light                                                                                             | Monochrome White On Dark                                                                                             |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Payment Badge - Monochrome Black on light.png" alt="Payment Badge - Monochrome Black on light.png" noZoom />    | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Payment Badge - Monochrome White on dark.png" alt="Payment Badge - Monochrome White on dark.png" noZoom />    |
| `<img alt="Cash App Pay" src="https://static.afterpay.com/en-US/integration/logo/icon/mono-light.svg" height="24" />` | `<img alt="Cash App Pay" src="https://static.afterpay.com/en-US/integration/logo/icon/mono-dark.svg" height="24" />` |

#### Squared

| Green On Dark                                                                                                                | Green                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Squared Payment Badge - Green on dark.png" alt="Squared Payment Badge - Green on dark.png" noZoom />               | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Squared Payment Badge - Green.png" alt="Squared Payment Badge - Green.png" noZoom />                       |
| `<img alt="Cash App Pay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/color.svg" height="24" />` | `<img alt="Cash App Pay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/color.svg" height="24" />` |

<br />

| Mono Light                                                                                                                        | Mono Dark                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Squared Payment Badge - mono light.png" alt="Squared Payment Badge - mono light.png" noZoom />                       | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/Squared Payment Badge - mono dark.png" alt="Squared Payment Badge - mono dark.png" noZoom />                       |
| `<img alt="Cash App Pay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/mono-light.svg" height="24" />` | `<img alt="Cash App Pay" src="https://static.afterpaycdn.com/en-US/integration/logo/squared-badge/mono-dark.svg" height="24" />` |

### Buttons

| Black Green                                                                                | Green Black                                                                                |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Button_Black.png" alt="$Pay_Button_Black.png" noZoom /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Button_Green.png" alt="$Pay_Button_Green.png" noZoom /> |

<br />

| Mono White                                                                                     | Mono Black                                                                                     |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Button_MonoBlack.png" alt="$Pay_Button_MonoBlack.png" noZoom /> | <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/$Pay_Button_MonoWhite.png" alt="$Pay_Button_MonoWhite.png" noZoom /> |

---

# Glossary of terms

List of commonly used terms and their definitions:

| Term                                 | Definition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| App Display Name                     | The App Name. The formal name of the integration. It should be representative of your brand to preserve continuity between your application and Cash App authorization screens.<br />It is shown to Cash App customers during the authorization flow and subsequently in their list of authorized integrations.                                                                                                                                                                                   |
| App Icon                             | The App Icon. It should match graphic assets used for your existing application. Format the icon to be 512 x 512 pixels, in PNG format and be representative of your brand. This preserves continuity between your application and Cash App authorization screens.<br />The icon is shown to Cash App customers during the authorization flow and subsequently in their list of authorized integrations.                                                                                          |
| Applicable Data Protection Laws      | All applicable federal, state, and local laws, rules and regulations of any applicable jurisdiction governing the processing of Personal Information.                                                                                                                                                                                                                                                                                                                                             |
| ASR - Authorization Success Rate     | The percentage of Cash App Pay (CAP) payment attempts that are successfully authorized.                                                                                                                                                                                                                                                                                                                                                                                                           |
| Block                                | Block Inc. and all of its subsidiaries and affiliates.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Brand                                | A customer-facing business entity that is a group of related merchants within Cash App. For example, Good Pour Coffee is a brand, and the Good Pour Coffee Shop at 1 Main Street is a merchant, under the Good Pour Coffee brand.                                                                                                                                                                                                                                                                 |
| Cash App                             | The Cash App application-based financial platform. Customers can use this platform to send peer-to-peer payments, store funds, and order physical and virtual debit cards. Customers can also use this platform to buy and store bitcoin, and obtain financial rewards using products or services featured within the application.                                                                                                                                                                |
| Cash App Account                     | A customer’s Cash App account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Cash App Pay (CAP)                   | The program that enables merchants to obtain a customer's authorization to use the customer’s Cash App account as a payment source for transactions with participating merchants.                                                                                                                                                                                                                                                                                                                 |
| Cash App Pay API (CAP API)           | The application program interface (API) that enables merchants to offer Cash App Pay as a payment method for customers.                                                                                                                                                                                                                                                                                                                                                                           |
| CIT - Customer Initiated Transaction | A transaction initiated by a customer to buy a product or service.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Client ID                            | A short application identifier that Cash App uses to attribute API calls to your integration.                                                                                                                                                                                                                                                                                                                                                                                                     |
| Client Secret or API Key             | A long lived secret token. This should be stored and transferred securely. Never check it into source control.                                                                                                                                                                                                                                                                                                                                                                                    |
| Customer                             | A Cash App user who uses Cash App Pay to pay for a transaction with a merchant.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Customer Request                     | A customer’s decision to use Cash App Pay following a prompt from a merchant or payment service provider (PSP) to a customer. The prompt offers the customer the opportunity to complete a transaction using Cash App Pay (including payments or refunds).                                                                                                                                                                                                                                        |
| Data Security Breach                 | Any breach of confidentiality with respect to personal information or other restricted information. It includes any loss, misuse, or unauthorized access, disclosure, alteration, destruction or acquisition of personal information or other restricted information.                                                                                                                                                                                                                             |
| Developer Portal                     | The website that contains Cash App Pay API-related documentation, software, and materials made available by Block. All of which may be amended or revised by Block from time to time and available at [Cash App Pay Developer Docs](/cash-app-pay-partner-api/guides/product-overview/how-cash-app-pay-works)                                                                                                                                                                                     |
| Dispute                              | Any claim by a customer related to a payment that states goods or services were not delivered or not delivered as expected. Or the transaction was not authorized, was duplicated or processed for an incorrect amount, or was otherwise not processed as expected by the customer.                                                                                                                                                                                                               |
| Event Webhook URL                    | This is a fully qualified publicly accessible URL that can be reached over the internet without authentication. Cash API servers call this URL with data describing events applicable to customer and/or system actions.                                                                                                                                                                                                                                                                          |
| Grant                                | An authorization from a customer for a merchant or PSP to take a payment from or issue a refund to a customer’s Cash App Account.                                                                                                                                                                                                                                                                                                                                                                 |
| Merchant                             | A person or entity that accepts Cash App Pay for the sale of goods or services to customers. Merchants may enter into agreements with payment service providers (PSPs) for the purpose of offering Cash App Pay to customers. Merchants must register, either directly or indirectly via their PSPs, with Block and use the Cash App Pay API to process Cash App Pay transactions for customers. A merchant may have one or more stores, websites, outlets, branches, or other commercial venues. |
| Merchant Use Policy (MUP)            | The Cash App Pay [Merchant Use Policy](/cash-app-pay-partner-api/guides/partnerships/merchant-use-policy)                                                                                                                                                                                                                                                                                                                                                                                         |
| MIT - Merchant Initiated Transaction | Transaction initiated by a merchant from an authorized payment source to recover a scheduled payment. For example, automatic billing for a subscription.                                                                                                                                                                                                                                                                                                                                          |
| NPUs - New Paying Users              | Customers new to paying with Cash App Pay.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| OTT - Over The Top                   | Technology (OTT services or platforms) that delivers streamed content via internet-connected devices. This is a known concern for anti-fraud detection, for example, account creation abuse.                                                                                                                                                                                                                                                                                                      |
| Payment                              | A type of transaction that uses Cash App Pay to send funds from a customer to a merchant in exchange for goods or services.                                                                                                                                                                                                                                                                                                                                                                       |
| Payment Service Provider (PSP)       | Service Provider (PSP)	A person or entity that offers payment processing and settlement services to facilitate the purchase of, or payment of bills for, goods or services through clearance and settlement systems by agreements with other persons or entities, including Merchants. To offer Cash App Pay as a clearance and settlement system to Merchants, PSPs must enter into Cash App Pay-related service agreements with Block.                                                          |
| Program Rules (Rules)                | The Cash App Pay program rules which, along with other applicable documents and agreements, govern the use of the Cash App Pay API and the offering of Cash App Pay to customers. See the latest [Program Rules](/cash-app-pay-partner-api/guides/partnerships/program-rules)                                                                                                                                                                                                                     |
| Refund                               | A type of transaction that uses Cash App Pay to send funds from a merchant to a customer.                                                                                                                                                                                                                                                                                                                                                                                                         |
| SVB(O) - Stored Value Balance (Only) | A setting that prevents customers using a linked debit card as a backup funding source.                                                                                                                                                                                                                                                                                                                                                                                                           |
| Transaction                          | Money movement using or otherwise related to Cash App Pay.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| WCO - Web Checkout                   | A front-end user interface that allows customers to complete payments using Cash App. Web Checkout acts as a web application in the browser, doing authentication before continuing with authorization.                                                                                                                                                                                                                                                                                           |

---

# Cash App Pay Status

We have two status pages for Cash App Pay:

* [Cash App Pay API Status](#cash-app-pay-api-status)
* [Cash App Application Status](#cash-app-application-status)

## Cash App Pay API Status

PSP (Payment Service Provider) Partners and directly integrated Merchants can monitor the status of Cash App Pay APIs on our [Partner Status Page.](https://status.partners.cash.app/)

<Note>
   Merchants who are integrated through a PSP should work with their PSP to be informed of the correct status of their Cash App Pay integration.
</Note>

<br />

<br />

![](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/CAP_API_status.png)
<Note> You can click on the **Subscribe to updates** button to see the different subscription options. <br /><br /><img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/CAP_subscribe.png" width="500" height="300" noZoom /></Note>

## Cash App Application Status

To verify any disruptions to end-using customers' Cash App services, go to the [Cash App status page.](https://status.cash.app/) <br /><br />
![](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/CAP_status1.png)

---

# FAQ: App Experience & Usage

**Q: What is Cash App Pay?**

**A:** Cash App Pay is a fast and simple payment method that allows Cash App customers to pay for purchases either by scanning a simple QR code or by choosing Cash App Pay at checkout.<br />

***

**Q: How do customers pay with Cash App Pay using their desktop during online checkout?**

**A:** Customers can pay with Cash App Pay from their desktop as follows:

1. Select Cash App Pay as their payment method during checkout
2. Scan the QR code generated by using their mobile device’s camera or Cash App’s QR scanner
3. Follow the prompts on their mobile device to complete the transaction<br />

***

**Q: How do customers pay with Cash App Pay using their mobile device?**<br />

**A:** Customers can pay with Cash App Pay using their Android or Apple mobile devices as follows:

1. Select Cash App Pay as their payment method during checkout
2. They will be redirected to Cash App
3. Follow the prompts on their mobile device to complete the transaction<br />

***

**Q: How do customers use Cash App Pay in stores?**

**A:** Cash App Pay allows Cash App users to pay Square sellers who have enabled Cash App Pay on their POS systems. To pay using Cash App Pay at Square POS systems:

1. Select Cash App Pay as their payment method during checkout
2. Scan the QR code generated by using their mobile device’s camera or Cash App’s QR scanner
3. Follow the prompts on their mobile device to complete the transaction<br />

***

**Q: Where can customers use Cash App Pay?**

**A:** Customers can use Cash App Pay in-store with sellers using the Square POS system. They can also use Cash App Pay to do online/e-commerce transactions both via desktop or using their mobile device.

***

**Q: Can customers use Cash App Pay if they’re an international customer?**
**A:** No, they cannot use Cash App Pay if they are an international customer. Cash App Pay is only available in the United States at this time.

***

**Q: Do customers always need a balance in Cash App to use Cash App Pay?**

**A:** Cash App Pay will first attempt to debit the customer’s stored balance. If the balance doesn’t cover the transaction total, 100% will be charged to a linked debit card.

---

# FAQ: Customer Identity Verification

**Q: What is Cash App’s Customer Identity Verification (IDV) process?**

**A:** To keep Cash App safe, customers who haven’t verified their identity on Cash App have limited access. To verify customers, we ask for their legal name, date of birth, and the last four digits of their Social Security Number (SSN). In some cases, we may also ask for the full SSN, residential address, unexpired government-issued photo ID, and/or income verification or source of funds.

See [Why do I need to verify my Identity (ID Verification)?](https://cash.app/help/US/en-us/6508-identity-verification)

***

**Q: What is the difference between Verified and Unverified customers?**

**A:** Customers who have not gone through the Identity Verification (IDV) process are considered unverified customers. Unverified customers can only spend from a linked debit card.

***

**Q: What is the breakdown between Verified and Unverified customers?**

**A:** Percentages vary, but less than one in ten Cash App Pay transactions are from unverified customers.

***

**Q: Are there daily transaction limits per user?**

**A:** Cash App accounts have weekly and monthly account outflow limits based on the identity verification status of Cash App customers. See the [Cash App Account Limits](https://cash.app/help/us/en-us/6543-account-limits) page for more information.

***

**Q: Does Cash App Pay work outside of the US?**

**A:** Currently, Cash App Pay does not work outside the USA. Only US Cash App accounts are eligible to use Cash App Pay. Cash App determines eligibility when the customer scans the Cash App Pay QR code or the customer redirects to Cash App on mobile. If the Cash App account is not tagged as a US customer, the customer sees a declined message in the app and will not be able to continue the transaction.

The country tagged to a Cash App account is influenced by the following:

* Country on file with the Cash App account (customer can set their address)
* Country specified during IDV
* Country of the associated linked instrument (bank account or debit card)

---

# FAQ: Pay Kit SDK

**Q: What is the difference between the QR code flow vs the mobile deep link flow?**

**A:** The QR code flow must be used for any use case where a mobile device would scan a QR code.
The mobile redirect URL must be used when you’re on a mobile device that can have Cash App installed.

***

**Q: How often is the QR code refreshed with Pay Kit SDK?**

**A:** QR codes refresh every 30 seconds and expire every 60 seconds. `refreshes_at` on the `auth_flow_triggers` property is the best place to learn when you must refresh.
Pay Kit SDK utilizes polling and refreshes the QR code once the current time is after `refreshes_at`.

***

**Q: Once a customer request has been approved, does Cash App prefer for the payment to be processed immediately or should the customer be redirected back to the merchant checkout where they can confirm payment?**

**A:** Cash App supports both approaches but prefers the payment to be processed immediately.

---

# FAQ: Disputes

**Q: What is the timeline for when a dispute must be responded to?**

**A:** The explicit deadline is specified on the `disputes` object. (`response_due_at` field).

---

# FAQ: Settlements

**Q: When are settlement reports uploaded?**

**A:** Our settlement jobs start running at 23:00 UTC. This is done via a SFTP file upload.

***

**Q: Do settlements include payments, refunds, and disputes?**

**A:** Yes, Cash App provides a net settlement process, deducting refund and dispute amounts from captured payment amounts.
Each net settlement will have a corresponding reconciliation report showing the amount of each payment, applicable fees, refunds, and dispute-related adjustments used in the calculation of the settlement amount. This report is delivered daily via SFTP to the PSP.

---

# FAQ: Returns and Refunds

**Q: How can the customer return an item they purchased with Cash App Pay?**

**A:** Cash App Pay returns follow our standard return policy. Cash App Pay transactions originating from the stored balance in the app will be refunded to the customer’s Cash App account balance. Cash App Pay transactions originating from a linked debit card or bank account will be refunded to the original card or bank account.

**Q: How do customers request a Cash App Pay Refund?**

**A:** Customers seeking a refund for their Cash App Pay payment must request a refund from the merchant directly. Should the merchant refund the transaction, it can take up to 10 business days for Cash App to receive the refund. As soon as Cash App receives the refund, the funds will automatically appear in your customer’s Cash App balance or linked debit card.<br />

<Note>
  Cash App has a set a maximum time limit of 7 years to issue the refund.
</Note>

---

# FAQ: Cash App Support

**Q: How do customers contact Cash App Customer Support?**

**A:** See [How to contact Cash Support](https://cash.app/help/us/en-us/3128-contact-cash-support) <br />

***

**Q: How can I learn more about Cash App or Cash App Pay?**

**A:** Cash App has a help knowledge base where you can search for your issue. Go to [cash.app/help](https://cash.app/help).<br />

---

# FAQ: Incentives

**Q: How are incentives being promoted?**

**A:** Incentives will be promoted in the **Discover** tab of Cash App using an in-app carousel.

***

**Q: Is Cash App Pay funding any incentives?**

**A:** For the launch, yes, a specific funding allocation is provided to Partners.

***

**Q: Can exclusions or T\&Cs be added to flow?**

**A:** No, Cash App Pay can’t support displaying T\&Cs with the incentive offer.

***

**Q: How much is the incentive (and can the Merchant influence it)?**

**A:** 10% off one purchase at launch Merchant per customer. No, the incentive is given and paid-for by Cash App Pay and the Merchant has no influence over it.

***

**Q: Is the Merchant still net-settled funds without an incentive discount?**

**A:** Yes, the Merchant is net-settled the total amount less any fees. The discount amount will not be deducted.

***

**Q: How do refunds/returns work?**

**A:** The maximum amount that the customer will be refunded is the amount they paid for the item. As an example, if a customer buys \$100 worth of goods at 10% off, the maximum amount that can be refunded to them is \$90.

***

**Q: Is this incentive for first-time customers only or on any transaction?**

**A:** This incentive can be applied by customers using Cash App Pay for the first time at each launch Merchant.

***

**Q: What if I already have a promotion going? Will this be an add-on?**\\

**A:** Yes, if a customer chooses to pay with Cash App Pay, they can add-on the incentive to any promotions that are already active.

***

**Q: Is there a maximum amount that can be redeemed for a particular incentive?**

**A:** Yes, the maximum amount that a customer can redeem for a single incentive is \$20 off one transaction.

***

**Q: Are there minimum thresholds for incentive offers?**

**A:** Yes, there must be a \$1 minimum transaction to apply the incentive.

***

**Q: What can a customer do if the incentive discount does not apply to their order?**

**A:** The customer can contact Cash App Customer Support for resolution. See [How to contact Cash Support](https://cash.app/help/us/en-us/3128-contact-cash-support).

***

**Q: Is the 10% off applied before taxes and shipping costs? Or inclusive of those costs?**

**A:** The 10% discount is calculated on the total settled amount (after applying taxes and shipping costs to the purchases). For example, a \$20 total purchase cost (that includes taxes and shipping) would get a \$2 discount.

See the following illustrative example that explains this:

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/incentive-calculation.png" alt="incentive-calculation.png" noZoom />

<br />

***

**Q: Where will the incentives be featured in the carousel and is it going to link to the Merchant website (or application)?**

**A:** The carousel will be on the Discover tab in Cash App. Tapping the item will take Customer to a half-sheet explaining the currently applicable Cash App Pay incentives.  Then, choosing the CTA (Call to Action) from the sheet will take them to the Merchant’s website (or application).

***

**Q: Will Cash App Pay provide tracking URLs after the redirect from the Cash App carousel to the Merchant’s website (or application)?**

**A:** At this time, Cash App does not provide tracking URLs  after the redirect from the Cash App carousel to the Merchant’s website or application. However, we plan to make this available in the future.

---

# Pay Kit Overview

Pay Kit is Cash App Pay’s JavaScript SDK that allows you to accept Cash App Pay online (both on the web and mobile).
Here are some of the things that you can do using Pay Kit:

* Rendering Cash App Pay button to an HTML element
* Customize the Cash App Pay button
* Fully managed and branded UI
* Advanced controls to support:
  * Validating a customer’s information
  * Using custom elements in checkout
  * Upselling to the customer

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/easy-name.png" alt="Screenshot 2023-01-12 at 9.42.58 AM.png" />

---

# Benefits of using Pay Kit

Pay Kit is the recommended integration path for partners integrating with Cash App. This is because Cash App Pay controls the end-to-end experience. These are some of the benefits our partners will experience:

* [Simplified Integration Path](#simplified-integration-path)
* [First-party Support](#first-party-support)

{/* * [Commerce and merchant services](#commerce-and-merchant-services)*/}

## Simplified Integration Path

Pay Kit SDK provides a streamlined integration path for developers by abstracting the Cash App Pay **customer linking** step to a drop-in Javascript library. The following are some of the attributes of a Simplified Integration Path that our partners can benefit from:

* **Supports desktop and mobile UX:** Pay Kit will automatically detect the customer device and facilitate the relevant Cash App Pay customer flow. On desktop devices, a QR code will be displayed to customers that they can scan with their phone to approve the payment. On mobile devices (iOS/Android), the customer will be redirected directly to Cash App to approve the payment.

{/* * **Supports forward and backward navigation:** Pay Kit handles both forward-navigation and backward-navigation scenarios on mobile.*/}

* **QR code rotation:** Pay Kit automatically rotates QR codes every 30 seconds for added security. Your development team does not have to create additional programming for doing this. Thus saving your engineering team's time and effort. <img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/easy-name2.png" alt="Screenshot 2023-01-12 at 9.45.49 AM.png" />

* **Cash App brand adherence:** Pay Kit ensures that you adhere to Cash App Pay's brand guidelines and requirements. Any branding and UI updates are automatic and do not need any intervention from your engineering teams.

* **Customer linking state changes:** Pay Kit emits a number of events throughout the lifecycle of a payment. One of the most important ones is `CUSTOMER_REQUEST_APPROVED` which is emitted after a customer approves a payment action such as a one-time payment.

## First-party support

Pay Kit is the recommended integration path for partners integrating with Cash App. Therefore, we can provide first-party support for partners integrated via Pay Kit in case things go wrong. In additon, Pay Kit pushes these upgrades automatically without additional development work required from partners or merchants.

{/*
## Commerce and Merchant Services
Cash App's **In-App Shopping and Incentives** is one of the main reasons that customers must try Cash App Pay beyond the inherent benefits of it being faster and easier to use than other payment methods. From a business perspective, In-App Shopping and Incentives helps us in new customer acquisition or new order acquisition for our merchants. 

Currently, the In-App Shopping and Incentives experience relies on Pay Kit to skip the normal Cash App Pay grant flow; instead, Cash App passes the grant token directly to the merchant website via a silent authentication process. Partners integrating via Pay Kit can expect In-App Shopping and Incentives functionality to work out of the box without additional development work. However, partners not utilizing Pay Kit are not eligible for In-App Shopping and Incentives as there is no available integration path independent from Pay Kit at the moment.

>**Note:** Pay Kit has the functionality to display merchants within Cash App’s **Discover** section.  Currently this feature is limited to merchants using PayKit web.


<img src="../../../../assets/images/Screenshot_20230112-103933 (1).png" style="width:300px;height:600px;" />

*/}

---

# Getting Started

Pay Kit is a JavaScript SDK that allows you to accept Cash App Pay online. On desktop devices, a QR code is displayed to customers. When they scan it with their phone, it opens Cash App to approve the payment.

On mobile devices such as iPhone and Android phones, the customer is redirected from your checkout experience to Cash App. Customers can then approve the payment before they are redirected back to your site.

<img src="https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/pay-kit-visualization.png" alt="Pay Kit visualization" noZoom />

<Note title="Before you start">
  You need a merchant identifier from the [Network API](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/network-api) to get started. We recommend that you have a working API integration.
</Note>

## Include the Pay Kit script

Pay Kit must be loaded from our global CDN and cannot be bundled into your application. This allows us to provide the best security and helps you avoid compliance issues.

```html
<script src="https://sandbox.kit.cash.app/v1/pay.js"></script>
```

<Note title="Ready for production?">
  Change the script URL to `https://kit.cash.app/v1/pay.js`
</Note>

## Initialize Pay Kit

Once loaded, start Pay Kit with the same [Client ID](/cash-app-pay-partner-api/guides/partnerships/partner-onboarding-requirements) you use for API access.

```js
const pay = await window.CashApp.pay({ clientId: 'YOUR_CLIENT_ID' });
```

<Note title="Ready for production?">
  Remember to change `clientId` from your sandbox ID (i.e. `CAS-CI_...`) to your production ID (i.e. `CA-CI_...`)
</Note>

## Listen for events

Pay Kit emits a number of events throughout the lifecycle of a payment. One of the most important ones is `CUSTOMER_REQUEST_APPROVED`. This is emitted after a customer approves a one-time payment or other action. You use this data to [create a payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment).

```js
const amount = {
  currency: 'USD',
  value: 1234, // $12.34
};
const scopeId = 'merchant_id_from_network_api';

pay.addEventListener(
  'CUSTOMER_REQUEST_APPROVED',
  ({ customerProfile, grants, referenceId }) => {
    // create your payment with the grant and same amount and scope
  }
);
```

<Note title="Mobile Redirect">
  After a customer has redirected back from Cash App on mobile devices, the `CUSTOMER_REQUEST_APPROVED` event occurs almost immediately. It's important to add your listener right after initializing.
</Note>

### Other supported events

`CUSTOMER_INTERACTION`

```js
pay.addEventListener(
  'CUSTOMER_INTERACTION',
  (customerInteractionData) => {
    console.log("customerInteractionData:", customerInteractionData);
  }
);

```

`CUSTOMER_DISMISSED`

```js
pay.addEventListener(
  'CUSTOMER_DISMISSED',
  (customerDismissedData) => {
    console.log("customerDismissedData:", customerDismissedData);
  }
);
```

`CUSTOMER_REQUEST_DECLINED`

```js
pay.addEventListener(
  'CUSTOMER_REQUEST_DECLINED',
  () => {
    console.log("Customer request declined");
  }
);
```

`CUSTOMER_REQUEST_FAILED`

```js
pay.addEventListener(
  'CUSTOMER_REQUEST_FAILED',
  (data) => {
    console.log("Customer request failed", data);
  }
);
```

## Render Cash App Pay

Pay Kit provides a fully managed user interface that you can customize to fit your checkout experience.

```html
<div id="cash-app-pay"><!-- populated by Pay Kit --></div>
```

```js
await pay.render('#cash-app-pay');
```

See [Technical Reference](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/technical-reference) to read more about customization.

## Create a customer request

Merchants request to perform actions on a customer's account. Approved actions result in grants which can be used to create payments or refunds. A merchant needs to be [created](/cash-app-pay-partner-api/api-reference/network-api/create-merchant) before you can create a one-time payment. We also assume you have calculated the correct amount and currency for the payment.

One-time, on-file, or both one-time and on-file payment actions are supported in the `customerRequest` API.

```js
async function onCashAppPayLoaded() {
	const pay = await window.CashApp.pay({ clientId: CASH_APP_CLIENT_ID });
    
    // Customer request supports both one-time on-file payments simultaneously. 
    const customerRequest = {
      referenceId: REFERENCE_ID, // perhaps a cart or checkout identifier
      redirectURL: window.location.href, // where mobile customers should be redirected to
      actions: {
        payment: {
          amount: {
            currency: 'USD',
            value: 1234, // $12.34
          },
          scopeId: MERCHANT_ID
        },
        onFile: {
          scopeId: BRAND_ID,
          accountReferenceId: EXTERNAL_ID
        },
      },
    };

await pay.customerRequest(customerRequest);
};
```

You should now have a functioning integration.

### Interactive code samples

#### On file payment

[https://codepen.io/erinn-xyz/pen/OPPLKxz](https://codepen.io/erinn-xyz/pen/OPPLKxz)

#### One-time payment

[https://codepen.io/erinn-xyz/pen/JooPgaK](https://codepen.io/erinn-xyz/pen/JooPgaK)

## Use cases

Discover all the ways you can use Pay Kit.

### Rendering

[Getting Started](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/getting-started) uses the simplest selector, a string. You can also render Cash App Pay to an HTML element.

```js
const target = document.querySelector('#cash-app-pay');
await pay.render(target);
```

#### Customize the Cash App Pay Button

The Cash App Pay button that is initially rendered can be customized to fit your payment experience.

##### Button shapes

Pay Kit provides two shapes: `round` (default) and `semiround` which has less rounded corners.

```js
await pay.render('#cash-app-pay', { button: { shape: 'semiround' } });
```

##### Button sizes

Pay Kit provides two sizes: `medium` (default) and `small` which is, predictably, smaller.

```js
await pay.render('#cash-app-pay', { button: { size: 'small' } });
```

##### Button themes

Pay Kit provides two themes: `dark` (default) and `light` which has a white background.

```js
await pay.render('#cash-app-pay', { button: { theme: 'light' } });
```

##### Button widths

Pay Kit provides two widths: `static` (default) and `full` which expands to fill its container.

```js
await pay.render('#cash-app-pay', { button: { width: 'full' } });
```

#### Advanced controls

By default, Pay Kit provides a fully managed and branded UI as you saw in the [Getting Started](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/getting-started) guide. You may want advanced controls in certain situations such as validating information a customer has provided during checkout before continuing. The `render` method accepts a boolean `manage` option that allows you to control when to begin the authorization flow. When the `manage` option is `false`, a `begin` method will be returned for you to call when you're ready.

```js
const target = document.querySelector('#cash-app-pay');

const { begin } = await pay.render(target, { manage: false });

let hasBegun = false;
target.addEventListener('click', () => {
  if (!hasBegun) {
    // TODO: validate customer information
    begin();
  }
  hasBegun = !hasBegun; // on desktop, clicks to the container could be closing the modal
});
```

Your checkout experience may want to use its own button for consistency across payment methods. When the `manage` option is `false`, you can also set the `button` option to `false` to prevent a Cash App Pay button from being rendered. You can now provide your own button and manage the authorization flow.

```html
<div id="cash-app-pay"></div>

<button class="checkout-button">Checkout</button>
```

```js
const { begin } = await pay.render('#cash-app-pay', {
  button: false,
  manage: false,
});

document.querySelector('.checkout-button').addEventListener('click', () => {
  begin();
});
```

##### Custom elements

Pay Kit provides [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to help customize checkout experiences while making it easy to follow brand guidelines.

The `<cash-app-pay-logo>` element renders a Cash App Pay logo which can be used when choosing a payment method or to enhance your checkout button.

```html
<button class="checkout-button">
  Continue with
  <cash-app-pay-logo size="small" theme="dark" />
</button>
```

The `<cash-app-pay-customer>` element renders the Cash App Pay logo and a customer's \$Cashtag with automatic truncation to easily fit your layout. You can combine these advanced render options and custom elements to use your own checkout button, manage the authorization flow, and display the Cash App Pay brand before and after approval with just a few lines of JavaScript.

```html
<cash-app-pay-customer class="hidden" />
```

```js
const button = document.querySelector('.checkout-button');

pay.addEventListener('CUSTOMER_REQUEST_APPROVED', ({ customerProfile }) => {
  button.classList.add('hidden'); // hide the checkout button

  const customer = document.querySelector('cash-app-pay-customer');
  customer.setAttribute('cashtag', customerProfile.cashtag);
  customer.classList.remove('hidden'); // show the cashtag
});

const { begin } = await pay.render('#cash-app-pay', {
  button: false,
  manage: false,
});

await pay.customerRequest(details);

button.addEventListener('click', () => {
  begin();
});
```

See [Technical Reference](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/technical-reference) to read more about customization.

### Placing another order in a single page app

After a successful checkout, the buyer may visit another page. Then, the buyer may come back to the checkout page to order without refreshing the page. Or in another scenario, you may want to provide an upsell right after the buyer completes the checkout.

When you need to take a new order with Pay Kit, you can call `restart` on the Pay instance:

```js
pay.restart();
```

When restarted, Pay Kit will forget about all previous authorizations and previously charged amounts. It will also remove all managed UI (for example, the Cash App Pay button, QR code modal, or approved Cashtag).

After restarting you can start another order as usual:

```js
pay.render(...) // to show a new Cash App Pay button
pay.customerRequest(...) // to specify amount for the new charge
```

We recommend that in a single page app, you should call `pay.restart()` whenever the buyer leaves the checkout page. When restarting at the exit of each page, if a buyer comes back to the checkout page, your initialization flow will work as usual without the buyer ever seeing the QR code for a previous customer request.

### Working with customer requests

Pay Kit allows you to `render` independently of creating a `customerRequest` so you can control the authorization experience as a customer checks out. Pay Kit's managed UI will adapt as you update your Customer Request.

```js
const details = {};
```

All `customerRequest` calls require a `redirectURL` which is where a customer will be taken after authorizing if they begin on a mobile device such as an iPhone or Android phone. This page should initialize Pay Kit and expect a `CUSTOMER_REQUEST_APPROVED` [event](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/technical-reference#addeventlistener). If approved, Pay Kit will render a customer's \$Cashtag, and you will be ready to create a payment.

```js
details.redirectURL = window.location.href;
```

You may optionally specify a `referenceId` which can be helpful to associate a cart, checkout, or order to a payment.

```js
details.referenceId = 'cart123';
```

#### One-time payments

The [Getting Started](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-web-overview/getting-started) guide uses the simplest action: a one-time payment. The `amount` should match what you intend to charge when [creating a payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment).

```js
details.actions = {
  payment: {
    amount: {
      currency: 'USD',
      value: 23.45, // $23.45
    },
    scopeId: 'merchant_id_from_network_api',
  },
};
```

#### On-file payments

You can also request to store a customer's account, allowing you to create payments on a recurring basis. The scope ID can be a client or brand account.

```js
details.actions.onFile = {
  scopeId: 'brand_id_from_network_api',
};
```

See [On-file Payments](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/on-file-payments) to know more.

#### Update customer requests

After creating a Customer Request, you can update it as long as the customer has not begun to interact (for example, scanned a QR code or been redirected to Cash App).

```js
const { update } = await pay.customerRequest(details);
```

Let's start simple by updating the `referenceId`:

```js
details.referenceId = 'cart456';

let success = await update(details);
if (success) {
  // referenceId was successfully updated
}
```

##### Update a one-time payment

Initially, we intended to charge the customer \$23.45, but if they changed their shipping option or applied a promotion, that amount value may have changed. You can apply the new value to `details` and then call `update`:

```js
details.actions.payment.amount.value = 3456; // $34.56
success = await update(details);
```

##### Update an on-file payment

Initially, we scoped our on-file action to the brand level which is a best practice. If you need to perform recurring charges for all of your brands, you can assign your client ID to `details` and then call `update`:

```js
details.actions.onFile.scopeId = 'client_id';
success = await update(details);
```

##### Remove an action

Initially, we constructed `details` to include both a one-time payment action and on-file action, but if a customer chooses not to enable recurring payments, the set of actions should be updated. You can delete an action from `details` and then call `update`:

```js
delete details.actions.onFile;
success = await update(details);
```

#### Unknown amounts

There may be times where `amount` for a one-time payment is difficult to calculate or simply unavailable. You may omit it, but be aware this may diminish the customer experience and increase the likelihood the payment is declined.

```js
await pay.customerRequest({
  actions: {
    payment: {
      scope_id: 'merchant_id_from_network_api',
    },
  },
  redirectURL: window.location.href,
});
```

## Going to production

When you use Pay Kit in production, remember to update the script URL and your Client ID.

```js
<script
-   src="https://sandbox.kit.cash.app/v1/pay.js"
+   src="https://kit.cash.app/v1/pay.js"
></script>

<script>
    const pay = await window.CashApp.pay({
-       clientId: 'CAS-CI_...',
+       clientId: 'CA-CI_...',
    });
</script>
```

Always load Pay Kit in a secure context (i.e. valid `https`).

---

# Technical Reference

## Pay

Pay Kit initializes to `window.CashApp` when you include our script and exposes an asynchronous `pay` method which requires a [Client ID](/cash-app-pay-partner-api/guides/partnerships/partner-onboarding-requirements). The Promise resolves an instance of `Pay`.

```html
<script src="https://kit.cash.app/v1/pay.js"></script>
<script>
  const pay = await window.CashApp.pay({ clientId: 'YOUR_CLIENT_ID');
</script>
```

{/* markdownlint-disable MD001 -- keeps table of contents hierarchical */}

#### Parameters

{/* markdownlint-enable MD001 -- keeps table of contents hierarchical */}

| Name       | Type     | Description                                                                                   |
| :--------- | :------- | :-------------------------------------------------------------------------------------------- |
| `clientId` | `string` | A short application identifier that Cash App uses to attribute API calls to your integration. |

### addEventListener

`Pay` exposes an `addEventListener` method that listens for events throughout the lifecycle of paying.

```js
pay.addEventListener('CUSTOMER_REQUEST_APPROVED', (data) => {});
```

#### Parameters

| Name       | Type                                                                                                                                                | Description   |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| `type`     | `"CUSTOMER_INTERACTION"` \| `"CUSTOMER_DISMISSED"` \| `"CUSTOMER_REQUEST_APPROVED"` \| `"CUSTOMER_REQUEST_DECLINED"` \| `"CUSTOMER_REQUEST_FAILED"` | event type    |
| `listener` | `PayEventListener`                                                                                                                                  | event handler |

**PayEventListener**: (`data`: `PayEventData`) => `void`

The `"CUSTOMER_REQUEST_DECLINED"` and `"CUSTOMER_REQUEST_FAILED"` events will not receive data.

**PayEventData**: `CustomerInteractionData` | `CustomerRequestData`

##### CustomerInteractionData

| Name       | Type      | Description                                                                               |
| :--------- | :-------- | :---------------------------------------------------------------------------------------- |
| `isMobile` | `boolean` | Value is `true` if the customer is using a mobile device where Cash App can be installed. |

##### CustomerRequestData

| Name              | Type                                          | Description                                                                       |
| :---------------- | :-------------------------------------------- | :-------------------------------------------------------------------------------- |
| `customerProfile` | `Customer`                                    | [Customer](/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer) |
| `grants`          | `Partial<Record<keyof Actions, GrantDetail>>` | A map of actions to details about a grant                                         |
| `referenceId`     | `string`                                      | A reference to your system (for example, a cart or checkout identifier)           |

##### Customer

The Customer who approved the request.

| Name      | Type     | Description                                                                                                |
| :-------- | :------- | :--------------------------------------------------------------------------------------------------------- |
| `cashtag` | `string` | Public identifier for the customer on Cash App. [Learn more](https://cash.app/help/us/en-us/3123-cashtags) |
| `id`      | `string` | Unique identifier for this customer issued by Cash App.                                                    |

##### Grants

The map of action to details about a grant may have keys `payment` or `onFile` (same as `Actions` below). `GrantDetail` has the following properties:

| Name        | Type     | Description                                                                                                             |
| :---------- | :------- | :---------------------------------------------------------------------------------------------------------------------- |
| `expiresAt` | `Date`   | When the grant will expire, at which point, you will need to create a new Customer Request.                             |
| `grantId`   | `string` | ID of Grant that can be used to [create a payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment). |

#### Returns

`void`

***

### removeEventListener

`Pay` exposes a `removeEventListener` method that removes an event listener previously registered with `addEventListener`.

```js
const createPayment = ({ grants }) => {
  // create your payment with the grant
};

pay.addEventListener('CUSTOMER_REQUEST_APPROVED', createPayment);

// when your application needs to destroy, teardown, unmount, etc.
pay.removeEventListener('CUSTOMER_REQUEST_APPROVED', createPayment);
```

#### Parameters

| Name       | Type                                                                                                                                                | Description   |
| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| `type`     | `"CUSTOMER_INTERACTION"` \| `"CUSTOMER_DISMISSED"` \| `"CUSTOMER_REQUEST_APPROVED"` \| `"CUSTOMER_REQUEST_DECLINED"` \| `"CUSTOMER_REQUEST_FAILED"` | event type    |
| `listener` | PayEventListener                                                                                                                                    | event handler |

#### Returns

`void`

***

### customerRequest

`Pay` exposes a `customerRequest` method that creates a [Customer Request](/cash-app-pay-partner-api/api-reference/customer-request-api/create-request) with one or more actions. You'll need a [Merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant) to create a payment.

```js
await pay.customerRequest({
  actions: {
    payment: {
      amount: {
        currency: 'USD',
        value: 1234, // $12.34
      },
      scopeId: 'merchant_id_from_network_api',
    },
  },
  redirectURL: window.location.href, // where mobile customers should be redirected to
  referenceId: 'your_reference_id', // perhaps a cart or checkout identifier
});
```

#### Parameters

The `customerRequest` method takes a `CustomerRequestDetails` object as its only argument. It has the following properties:

| Name                     | Type      | Description                                                                                                                 |
| :----------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `actions`                | `Actions` | Actions the customer will allow the merchant to perform.                                                                    |
| `redirectURL`            | `string`  | The destination for the customer after approving (or declining) in Cash App for mobile redirect flow. Must be a secure URL. |
| `referenceId` (optional) | `string`  | A reference to your system (for example, a cart or checkout identifier). Maximum length 1024 characters.                    |

**Actions** is an object with optional `onFile` and `payment` properties, but at least one must exist.

##### onFile

| Name                 | Type     | Description                                                             |
| :------------------- | :------- | :---------------------------------------------------------------------- |
| `scopeId`            | `string` | ID of the client or brand account that will charge Customers.           |
| `accountReferenceId` | `string` | Identifier of the account or Customer associated to the on-file action. |

##### payment

| Name                | Type     | Description                                                                  |
| :------------------ | :------- | :--------------------------------------------------------------------------- |
| `amount` (optional) | `Amount` | The amount to charge the customer.                                           |
| `scopeId`           | `string` | The ID of the client, brand, or merchant account that will charge customers. |

###### Amount

Amount to charge the customer.

| Name       | Type     | Description                                                              |
| :--------- | :------- | :----------------------------------------------------------------------- |
| `currency` | `string` | "USD" is currently the only accepted value.                              |
| `value`    | `number` | The lowest unit of the associated currency (for example, cents for USD). |

#### Returns

`Promise<CustomerRequestController>`

##### CustomerRequestController

`CustomerRequestController` controls the Customer Request.

```js
const details = { referenceId: 'initial', redirectURL: '...', actions: { ... } };
const { update } = await pay.customerRequest(details)

details.referenceId = 'final'

const success = await update(details)
if (success) {
  // continue creating payment with latest details
} else {
  // creating payment could possibly fail if a more complex change was made to `details`
}
```

###### update

The `update` method will update your Customer Request. The same validation applies (for example, must have at least one action) except `redirectURL` cannot be changed.

| Name      | Type                     | Description                                        |
| :-------- | :----------------------- | :------------------------------------------------- |
| `details` | `CustomerRequestDetails` | New value for the details of the Customer Request. |

Returns `Promise<boolean>` to indicate if the update was successful. An example of when an update would not be successful is if the Customer Request has already been approved.

***

### render

`Pay` exposes a `render` method that renders a managed Cash App Pay UI into your DOM.

```js
await pay.render('#cash-app-pay');
```

#### Parameters

| Name                 | Type                      | Description                                           |
| :------------------- | :------------------------ | :---------------------------------------------------- |
| `target`             | `string` \| `HTMLElement` | The location to insert Cash App Pay's UI in your DOM. |
| `options` (optional) | `RenderOptions`           | See details about `RenderOptions` below.              |

**RenderOptions** is an object with these optional properties:

| Name     | Type                       | Description                                                                                                                         |
| :------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `button` | `ButtonOptions` \| `false` | See details about `ButtonOptions` below. If `false`, no button will be rendered, and you should provide your own.                   |
| `manage` | `boolean`                  | If `true`, Pay Kit will manage beginning the authorization flow. See `RenderController` below for more details. Defaults to `true`. |

**ButtonOptions** is an object with these optional properties:

| Name    | Type                       | Description                                                |
| :------ | :------------------------- | :--------------------------------------------------------- |
| `shape` | `"round"` \| `"semiround"` | The shape of the Cash App Pay button. Defaults to "round"  |
| `size`  | `"medium"` \| `"small"`    | The size of the Cash App Pay button. Defaults to "medium"  |
| `theme` | `"dark"` \| `"light"`      | The theme of the Cash App Pay button. Defaults to "dark"   |
| `width` | `"full"` \| `"static"`     | The width of the Cash App Pay button. Defaults to "static" |

#### Returns

`Promise<RenderController>`

##### RenderController

`RenderController` can control rendering.

###### begin

The `begin` method will begin the authorization flow for the customer if the `manage` option was `false`. Otherwise, it is a no-op. To use your own button and control the flow, you must set both `manage` and `button` to `false`.

```js
const { begin } = await pay.render('#cash-app-pay', {
  button: false,
  manage: false,
});

document.querySelector('#my-checkout-button').addEventListener('click', () => {
  // NB: a customer may be redirected away from your page
  begin();
});
```

###### destroy

The `destroy` method will remove the Cash App Pay UI from your DOM.

```js
const { destroy } = await pay.render('#cash-app-pay');

// when your application needs to teardown, unmount, etc.
destroy();
```

### restart

`Pay` exposes a `restart` method that removes all rendered UI as well as the current customer request.

In a single page app,`pay.restart()` must be called whenever the buyer leaves the checkout page. You can only make a new customer request after restart, if the current customer request is approved.

```js
await pay.restart();
```

#### Parameters

None

#### Returns

`void`

## Custom elements

Pay Kit provides [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to help customize checkout experiences while making it easy to follow brand guidelines.

### Logo

The `<cash-app-pay-logo>` element renders the Cash App Pay logo and can be customized with two attributes:

| Name  | Type                    | Description            |
| :---- | :---------------------- | :--------------------- |
| size  | `"medium"` \| `"small"` | The size of the logo.  |
| theme | `"dark"` \| `"light"`   | The theme of the logo. |

### Customer

The `<cash-app-pay-customer>` element renders the Cash App Pay logo and a customer's \$Cashtag. The `cashtag` attribute is required and will be automatically truncated if needed. The element will grow to fill its parent container.

```html
<cash-app-pay-customer cashtag="$jack" />
```

---

# React Native Requirements

React Native mobile applications require extra configuration for both iOS and Android to ensure that Cash App deeplinks successfully during the Cash App Pay mobile user flow. This is caused because your application cannot see, or directly interact with, most external packages without explicitly requesting allowance. Therefore, you must declare your app’s need for increased visibility with Cash App.

## iOS

### Problem

Launch Services provides support for launching apps and matching document types to apps. Therefore, the keys recognized by Launch Services allow you to specify the desired execution environment for your code packages. See more at [Launch Services Keys.](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/uid/TP40009250-SW14)

### Solution

The following configuration must be added to the `info.plist` file:

```.plist
<key>LSApplicationQueriesSchemes</key>
<array> 
    <string>cashme</string>
</array>
```

## Android

### Problem

When your app queries information about other apps that are installed on an Android (11 or higher) device, the information is filtered by default. This filtering behavior means that your app can’t detect all the apps installed on the device. This helps minimize the potentially sensitive information that your app can access but doesn't really need for its use cases. See more at [Package visibility filtering on Android.](https://developer.android.com/training/package-visibility)

### Solution

The following configuration must be added to the `AndroidManifest.xml` file:

```xml
<queries>
    <intent>  
        <action android:name="android.intent.action.VIEW" /> 
            <data 
                android:host="*" 
                android:scheme="cashme" /> 
    </intent> 
</queries>
```

---

# Pay Kit iOS: Getting Started

## Code language

To control and modify the Pay Kit iOS SDK, you can use the Swift language or the Objective-C language. The code examples and states on this page are in Swift.

See the [Objective-C Examples and States](#objective-c-examples-and-states) section at the bottom of this page for code examples and states in Objective-C.

## Prerequisites

* All integrations require a Client ID provided by Cash App (see [Deliverables: Cash App Pay Partner Engineering](/cash-app-pay-partner-api/guides/partnerships/partner-onboarding-requirements))
* To authorize payments for a specific Merchant or Brand, you'll need to [create a Merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant) or [create a Brand](/cash-app-pay-partner-api/api-reference/network-api/create-brand) using the Cash App REST APIs.

<Info>
  One-time payments can be authorized for a Merchant, Brand, or Client. On-file payments can only be authorized for a Brand or Client.
</Info>

## Step 1 Implement the Cash App Pay Observer Protocol

To receive updates from Pay Kit, you’ll need to implement the Cash App Pay Observer protocol. Your checkout view controller can conform to this protocol, or you can create a dedicated observer class.

The `CashAppPayObserver` protocol contains only one method:

```swift
func stateDidChange(to state: CashAppPayState) {
	// handle state changes
}
```

Your implementation should switch on the `state` parameter and respond to each of the [state changes](#states). Below is a partial implementation of the most important states.

```swift
func stateDidChange(to state: CashAppPayState) {
    switch state {
    case let .readyToAuthorize(customerRequest):
        // The customer is ready to authorize the Customer Request by deep linking in to Cash App.
        // Enable the Cash App Pay Button.
    case let .approved(request: customerRequest, grants: grants):
        // The customer has deep linked back to your App from Cash App and they approved the Customer Request!
        // The checkout is now complete.
    case let .declined(customerRequest):
        // The customer has deep linked back to your App from Cash App and the Customer Request is declined.
        // This Customer Request is in a terminal state and any subsequent actions on this Customer Request will yield an error.
        // To retry the customer will need to restart the Customer Request flow.
        // You should make sure customers can select other payment methods at this point.
    case .redirecting:
        // The customer is being redirected to Cash App you can present a loading spinner if desired.
        // NOTE: In the event that the customer does not have Cash App installed and navigates back to your app then it is
        // up to you to set a reasonable timeout after which you dismiss the loading spinner and treat the Customer Request as failed.
    case .integrationError:
        // There is an issue with the way you are transitioning between states. Refer to the documentation to ensure you are
        // moving between states in the correct order.
        // You can perform a valid transition from this state.
    case .apiError:
        // Cash App Pay API is suffering degraded performance. You can can retry your event or discard this checkout.
        // Retrying may fix the issue or reach out to Developer Support for additional help.
    case .unexpectedError:
        // This should never happen however in the event you receive this please reach out to Developer Support to diagnose the issue.
    case .networkError:
        // The Cash App Pay SDK attempts to retry network failures however in the event that a customer is unable
        // to perform their checkout due to network connectivity issues you may want to retry the checkout.
    ...
    // handle the other state changes
    ...
    }
}
```

Some of these possible states are for information only, but most drive the logic of your integration. A full list of states to handle are listed in the table below:

### States

> You must update your UI in response to these state changes.

| State              | Description                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `readyToAuthorize` | Show a Cash App Pay button in your UI and call `authorizeCustomerRequest()` when it is tapped.                    |
| `approved`         | Grants are ready for your backend to use to create a payment.                                                     |
| `declined`         | Customer has declined the Cash App Pay authorization and must start the flow over or choose a new payment method. |

### Terminal states

These states cannot transition further and attempting to action on a Customer Request that is in a terminal state will result in an error.

| State      | Description                                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `approved` | Grants are ready for your backend to use to create a payment.                                                     |
| `declined` | Customer has declined the Cash App Pay authorization and must start the flow over or choose a new payment method. |

<Warning>
  Customer Requests can fail for a number of reasons, such as when customer exits the flow prematurely or are declined by Cash App for risk reasons. You must respond to these state changes and be ready to update your UI appropriately.
</Warning>

### Error states

| State              | Description                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `integrationError` | A fixable bug in your integration.                                                                      |
| `apiError`         | A degradation of Cash App Pay server APIs. Your app should temporarily hide Cash App Pay functionality. |
| `unexpectedError`  | A bug outside the normal flow. Report this bug (and what caused it) to Cash App Developer Support.      |
| `networkError`     | A networking error, likely due to poor internet connectivity.                                           |

### Informational states

| State                     | Description                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `notStarted`              | Ready for a Create Customer Request to be initiated.                                                               |
| `creatingCustomerRequest` | CustomerRequest is being created. For information only.                                                            |
| `updatingCustomerRequest` | CustomerRequest is being updated. For information only.                                                            |
| `redirecting`             | SDK is redirecting to Cash App for authorization. Show loading indicator if desired.                               |
| `polling`                 | SDK is retrieving authorized CustomerRequest. Show loading indicator if desired.                                   |
| `refreshing`              | CustomerRequest is being refreshed as a result of the AuthFlowTriggers expiring. Show loading indicator if desired |

## Step 2 Implement URL handling

To use Pay Kit iOS, Cash App must be able to call a URL that will redirect back to your app. The simplest way to accomplish this is via [Custom URL Schemes](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app), but if your app supports [Universal Links](https://developer.apple.com/ios/universal-links/) you can use those URLs as well.

Choose a unique scheme for your application and register it in Xcode from the **Info** tab of your application’s Target. For example, the TipMyCAP application that exercises the SDK functionality configures a scheme as follows:

![configure\_scheme.png](https://files.buildwithfern.com/cash-app.docs.buildwithfern.com/2026-01-27T23:03:44.161Z/cash-api-docs/assets/images/configure_scheme.png)

You’ll pass a URL that uses this scheme (or a Universal Link your app handles) into the `createCustomerRequest()` method that starts the authorization process.

When your app is called back by Cash App, post the `CashAppPay.RedirectNotification` from your `AppDelegate` or `SceneDelegate`, and the SDK will handle the rest:

```swift
import UIKit
import PayKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let url = URLContexts.first?.url {
            NotificationCenter.default.post(
                name: CashAppPay.RedirectNotification,
                object: nil,
                userInfo: [UIApplication.LaunchOptionsKey.url : url]
            )
        }
    }
}
```

<Error title="Do Not Skip This Step!">
  This step is vital to ensuring the integration works correctly! You may find that in testing environments this step is not required however in production environments you will see a high number of customers not being able to complete their checkout because the SDK never enters the polling state.
</Error>

## Step 3 Instantiate Pay Kit iOS

When you’re ready to authorize a payment using Cash App Pay,

1. Instantiate the SDK with your Client ID.
2. The SDK defaults to point to the `.production` endpoint. For development, set the endpoint to `.sandbox`.
3. Add your observer to the SDK.

For example, from your checkout view controller that implements the `CashAppPayObserver` protocol, you might instantiate the SDK to be:

```swift
private let sandboxClientID = "YOUR_CLIENT_ID"
private lazy var sdk: CashAppPay = {
    let sdk = CashAppPay(clientID: sandboxClientID, endpoint: .sandbox)
    sdk.addObserver(self)
    return sdk
}()
```

<Warning title="Make Sure You Retain The SDK!">
  You must strongly retain the SDK otherwise you will never recieve state changes.
</Warning>

## Step 4 Create a Customer Request

You can create a customer request as soon as you know the amount you’d like to charge or if you'd like to create an on-file payment request. You must create this request as soon as your checkout view controller loads, so that your customer can authorize the request without delay.

### Example

To charge \$5.00, your `createCustomerRequest` call might look like this:

```swift
private let sandboxBrandID = "YOUR_BRAND_ID"

override func viewDidLoad() {
    super.viewDidLoad()
    // load view hierarchy
    sdk.createCustomerRequest(
        params: CreateCustomerRequestParams(
            actions: [
                .oneTimePayment(
                    scopeID: brandID,
                    money: Money(amount: 500, currency: .USD)
                )
            ],
            channel: .IN_APP,
            redirectURL: URL(string: "tipmycap://callback")!,
            referenceID: nil,
            metadata: nil
        )
    )
}
```

Your Observer's state changes to `.creatingCustomerRequest`, then `.readyToAuthorize` with the created `CustomerRequest` structure as an associated value.

## Step 5 Authorize the Customer Request

Once the SDK is in the `.readyToAuthorize` state, you can store the associated `CustomerRequest` and display a Cash App Pay button. When the customer taps the button, you can authorize the customer request.

### Example

```swift
@objc func cashAppPayButtonTapped() {
    sdk.authorizeCustomerRequest(request)
}
```

Your app will redirect to Cash App for authorization. When authorization is completed, your redirect URL will be called and the `RedirectNotification` will post. Then the SDK will fetch your authorized request and return it to your Observer, as part of the change to the `.approved` state.

### Unhappy Path

If the Customer does not have Cash App installed on their device then they will redirect to a webpage prompting them to download Cash App. In the event the customer does not download Cash App, then the SDK will remain in the `polling` state. The SDK does not handle this edge case and instead it is up to the implementor to set a reasonable timeout and treat the checkout as failed once that timeout is exceeded. It is suggested to dismiss any loading states and restart the Cash App Pay flow as to not block the customer from checking out.

## Step 6 Pass Grants to the Backend and Create Payment

The approved `CustomerRequest` will have `Grants` associated with it that can be used with Cash App's [Create Payment](/cash-app-pay-partner-api/api-reference/network-api/create-payment) API. Pass those grants to your backend and call the Create Payment API as a server-to-server call to complete your payment.

---

# Pay Kit UI

`PayKitUI` provides an unmanaged `CashAppPayButton` and a `CashAppPaymentMethod` view in both `UIKit` and `SwiftUI`.

These views accept a `SizingCategory` to specify the preferred size of the view within your app. They also support light/dark themes by default.
These views must be used as-is, without modification.

### CashAppPayButton

This is an example of `CashAppPayButton`:

<img noZoom img width="368" alt="image" src="https://user-images.githubusercontent.com/8743061/216639753-159f2b3e-21be-4113-8a92-fd77e93acd12.png" />

You can use the following example for instantiating the button:

```swift
let button = CashAppPayButton(size: .small, onClickHandler: {})
```

### CashAppPaymentMethod

This is an example of `CashAppPaymentMethod`:

<img noZoom img width="250" alt="image" src="https://user-images.githubusercontent.com/8743061/216639415-49591e1e-046e-49a0-b480-b6249394254d.png" />

You can use the following example for instantiating the button:

```swift
let paymentMethod = CashAppPaymentMethod(size: .small)
paymentMethod.cashTag = "$jack"
```

## Analytics

If you want to monitor your integration to ensure customers are appropritately transitioning through the Cash App Pay funnel then you can track a metric in each of the `CashAppPayState`'s and build a funnel using the Customer Request ID.

## (iOS only) Pay Kit mobile redirect limitations

iOS has a limitation that causes an interstitial page to show, requiring an extra user interaction. This happens if the time taken between the user clicking the Cash App Pay button and Pay Kit attempting to deep link exceeds 1 second.

### Issue Description

[Universal linking](https://developer.apple.com/ios/universal-links/) on iOS has a limitation based on an "interaction threshold". A customer input (for example, touch, click) is required for a universal link to open an app. If the linking is done programmatically, by updating `location.href` for example, there is a limit of 1 second between the interaction and the actual redirection for a universal link to properly deep link into an app. If the limit is exceeded, the universal link is opened as a normal webpage instead.

When Pay Kit is managing the Cash App Pay button, the 1 second threshold will never be exceeded. However, when using the `manage` option to control Pay Kit manually, you must take care that the 1 second threshold is not hit.

Examples for how this may happen are: adding additional API calls after the Customer has interacted with the button but before Pay Kit is called, or running other types of form validation. Any such work should be done prior to the customer interacting with the button to avoid any extra work that might exceed the 1 second threshold which will cause the interstitial to show.

## Objective-C Examples and States

### General Information

| **Swift**                         | **Objective-C**                              |
| --------------------------------- | -------------------------------------------- |
| `CashAppPayObserver`              | `CAPCashAppPayObserver`                      |
| `CashAppPay.RedirectNotification` | `[CAPCashAppPay RedirectNotification]`       |
| `.production / .sandbox`          | `CAPEndpointProduction / CAPEndpointSandbox` |

### Step 1

[Step 1 Implement the Cash App Pay Observer Protocol](#step-1-implement-the-cash-app-pay-observer-protocol)

The `CashAppPayObserver` protocol contains only one method:

Swift code:

```swift
func stateDidChange(to state: CashAppPayState) {
    // handle state changes
}
```

The `CAPCashAppPayObserver` protocol contains only one method:

Objective-C code:

```Objective-C
-  (void)stateDidChangeTo:(CAPCashAppPayState *)state {
    // handle state changes
}
```

**States**

> You must update your UI in response to these state changes.

| **Swift**          | **Objective-C**                      |
| ------------------ | ------------------------------------ |
| `readyToAuthorize` | `CAPCashAppPayStateReadyToAuthorize` |
| `approved`         | `CAPCashAppPayStateApproved`         |
| `declined`         | `CAPCashAppPayStateDeclined`         |

### Terminal states

| **Swift**  | **Objective-C**              |
| ---------- | ---------------------------- |
| `approved` | `CAPCashAppPayStateApproved` |
| `declined` | `CAPCashAppPayStateDeclined` |

**Error States**

| **Swift**          | **Objective-C**                      |
| ------------------ | ------------------------------------ |
| `integrationError` | `CAPCashAppPayStateIntegrationError` |
| `apiError`         | `CAPCashAppPayStateApiError`         |
| `unexpectedError`  | `CAPCashAppPayStateUnexpectedError`  |
| `networkError`     | `CAPCashAppPayStateNetworkError`     |

### Informational states

| **Swift**                 | **Objective-C**                             |
| ------------------------- | ------------------------------------------- |
| `notStarted`              | `CAPCashAppPayStateNotStarted`              |
| `creatingCustomerRequest` | `CAPCashAppPayStateCreatingCustomerRequest` |
| `updatingCustomerRequest` | `CAPCashAppPayStateUpdatingCustomerRequest` |
| `redirecting`             | `CAPCashAppPayRedirecting`                  |
| `polling`                 | `CAPCashAppPayStatePolling`                 |
| `refreshing`              | `CAPCashAppPayStateRefreshing`              |
| `redirecting`             | `CAPCashAppPayStateRedirecting`             |

### Step 2

[Step 2 Implement URL Handling](#step-2-implement-url-handling)

When your app is called back by Cash App, post the `CashAppPay.RedirectNotification` from your `AppDelegate` or `SceneDelegate`, and the SDK will handle the rest:

Swift code:

```swift
import UIKit
import PayKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let url = URLContexts.first?.url {
            NotificationCenter.default.post(
                name: CashAppPay.RedirectNotification,
                object: nil,
                userInfo: [UIApplication.LaunchOptionsKey.url : url]
            )
        }
    }
}
```

When your app is called back by Cash App, post the `[CashAppPay.RedirectNotification]` from your `AppDelegate` or `SceneDelegate`, and the SDK will handle the rest:

Objective-C code:

```Objective-C
@import PayKit;

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    if ([URLContexts count] > 0) {
        NSURL *url = ((UIOpenURLContext*)[[URLContexts allObjects] firstObject]).URL;
        [[NSNotificationCenter defaultCenter]
         postNotificationName:[CAPCashAppPay RedirectNotification]
         object:NULL
         userInfo:@{UIApplicationLaunchOptionsURLKey: url}
        ];
    }
}
```

<Error title="Do Not Skip This Step!">
  This step is vital to ensuring the inetgration works correctly! You may find that in testing environments this step is not required however in production environments you will see a high number of customers not being able to complete their checkout because the SDK never enters the polling state.
</Error>

### Step 3

[Step 3 Instantiate Pay Kit iOS](#step-3-instantiate-pay-kit-ios)

For example, from your checkout view controller that implements the `CashAppPayObserver` protocol, you might instantiate the SDK to be:

Swift code:

```swift
private let sandboxClientID = "YOUR_CLIENT_ID"
private lazy var sdk: CashAppPay = {
    let sdk = CashAppPay(clientID: sandboxClientID, endpoint: .sandbox)
    sdk.addObserver(self)
    return sdk
}()
```

<Warning title="Make Sure You Retain The SDK!">You must strongly retain the SDK otherwise you will never recieve state changes.</Warning>
For example, from your checkout view controller that implements the `CashAppPayObserver` protocol, you might instantiate the SDK to be:

Objective-C code:

```Objective-C
In the .h file:
@property (nonatomic, strong) CAPCashAppPay *sdk;

In the .m file:
NSString *sandboxClientID = @"YOUR_CLIENT_ID";
self.sdk = [[CAPCashAppPay alloc]initWithClientID:sandboxClientID endpoint:CAPEndpointSandbox];
[_sdk addObserver:self];
```

### Step 4

[Step 4 Create a Customer Request](#step-4-create-a-customer-request)

To charge \$5.00, your `createCustomerRequest` call might look like this:

Swift code:

```swift
private let sandboxBrandID = "YOUR_BRAND_ID"

override func viewDidLoad() {
    super.viewDidLoad()
    // load view hierarchy
    sdk.createCustomerRequest(
        params: CreateCustomerRequestParams(
            actions: [
                .oneTimePayment(
                    scopeID: brandID,
                    money: Money(amount: 500, currency: .USD)
                )
            ],
            channel: .IN_APP,
            redirectURL: URL(string: "tipmycap://callback")!,
            referenceID: nil,
            metadata: nil
        )
    )
}
```

To charge \$5.00, your `createCustomerRequestWithParams` call might look like this:

Objective-C code:

```Objective-C
- (void)viewDidLoad {
    [super viewDidLoad];
    // load view hierarchy
    NSString *sandboxBrandID = @"YOUR_BAND_ID";
    CAPMoney *oneDollar = [[CAPMoney alloc] initWithAmount:500 currency:CAPCurrencyUSD];
    [_sdk createCustomerRequestWithParams:[
        [CAPCreateCustomerRequestParams alloc]
        initWithActions:@[[CAPPaymentAction oneTimePaymentWithScopeID:sandboxBrandID money:oneDollar]]
        redirectURL:[[NSURL alloc]initWithString:@"paykitdemo://callback"]
        referenceID:NULL
        metadata:NULL
    ]
    ];
}
```

### Step 5

[Step 5 Authorize the Customer Request](#step-5-authorize-the-customer-request)

When the customer taps the button, you can authorize the customer request.

**Example**

Swift code:

```swift
@objc func cashAppPayButtonTapped() {
    sdk.authorizeCustomerRequest(request)
}
```

When the customer taps the button, you can authorize the customer request.

**Example**

Objective-C code:

```Objective-C
- (IBAction)cashAppPayButtonTapped:(id)sender {
    [_sdk authorizeCustomerRequest:request]
}

```

### Unhappy Path

If the Customer does not have Cash App installed on their device then they will redirect to a webpage prompting them to download Cash App. In the event the customer does not download Cash App, then the SDK will remain in the `polling` state. The SDK does not handle this edge case and instead it is up to the implementor to set a reasonable timeout and treat the checkout as failed once that timeout is exceeded. It is suggested to dismiss any loading states and restart the Cash App Pay flow as to not block the customer from checking out.

---

# Pay Kit Android: Getting Started

**Integrate with Cash App Pay's Android SDK**

***

## Prerequisites

* All integrations require a Client ID provided by Cash App (see [Deliverables: Cash App Pay Partner Engineering](/cash-app-pay-partner-api/guides/partnerships/partner-onboarding-requirements))
* To authorize payments for a specific Merchant or Brand, you'll need to [create a Merchant](/cash-app-pay-partner-api/api-reference/network-api/create-merchant) or [create a Brand](/cash-app-pay-partner-api/api-reference/network-api/create-brand) using the Cash App REST APIs.

> One-time payments can be authorized for a Merchant, Brand, or Client. On-file payments can only be authorized for a Brand or Client.

## General SDK information

* Minimum Android supported SDK: `21`
* Target Android SDK: `31`

## Step 1: Import the dependency

You can get the latest version of the SDK from Maven. This is the import definition using Gradle:

```
implementation "app.cash.paykit:core:2.5.0"
```

For definitions of other build systems, see [Cash App Pay Android SDK on Maven Central](https://central.sonatype.com/artifact/app.cash.paykit/core/2.5.0/overview).

<Note>
  The size of the Version `v2.5.0` of the SDK is `12.3 kB`.
</Note>

## Step 2: Create an SDK instance

To create a new instance of the SDK, you must pass the  `client ID` . This is a required field.

You should use `CashAppPayFactory` to create an instance of the SDK. When setting up the SDK you'll need to specify the environment you will use, Sandbox or Production.
The function `createSandbox()` will create an SDK instance in the Sandbox environment.

> You should use the Sandbox environment during the development phase and Production environment for your actual production releases.

<br />Creating a Sandbox SDK instance:

```kotlin
val cashAppPay : CashAppPay = CashAppPayFactory.createSandbox(sandboxClientID)
```

<br />Creating a Production SDK instance:

```kotlin
val cashAppPay : CashAppPay = CashAppPayFactory.create(clientID)
```

<Tip title="Optional">
  We recommend using our [Sandbox App](/cash-app-pay-partner-api/guides/technical-guides/sandbox/sandbox-app) to compare the Sandbox environment of the SDK during your development phase.
</Tip>

## Step 3: Register for state updates

To receive updates from Pay Kit, you’ll need to implement the `CashAppPayListener` interface. The interface exposes a single function, which gets called whenever there’s an internal state change emitted by the SDK:

```kotlin
interface CashAppPayListener {
   fun cashAppPayStateDidChange(newState: CashAppPayState)
}
```

You register with the SDK instance you’ve created above:

```kotlin
cashAppPay.registerForStateUpdates(this)
```

You should also use the `unregister` function when you're done with the SDK:

```kotlin
cashAppPay.unregisterFromStateUpdates()
```

### States

`CashAppPayState` is a sealed class parameter. We suggest that you use a Kotlin `when` statement on it.  Some of these possible states are for information only, but most drive the logic of your integration. The most critical states to handle are in the table below:

| State                      | Description                                                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ReadyToAuthorize`         | Show a Cash App Pay button in your UI and call `authorizeCustomerRequest()` when it is tapped.                                                                                       |
| `Approved`                 | Grants are ready for your backend to use to create a payment.                                                                                                                        |
| `Declined`                 | Customer has declined the Cash App Pay authorization and must start the flow over or choose a new payment method.                                                                    |
| `CashAppPayExceptionState` | The general wrapper state for exceptions. These can range from ***integration*** errors to **network** errors. The exception states are emitted only for unrecoverable error states. |

## Step 4: Handling Deep Linking

The authorization flow will bring Cash App to the foreground on the Customer’s device. After the Customer either authorizes or declines the request, your app must be returned to the foreground. This means that we must call your app from Cash App.  This is accomplished by [declaring an incoming intent filter](https://developer.android.com/training/app-links/deep-linking#adding-filters) on your app's Android Manifest and passing a corresponding redirect URI that uses the SDK when creating a Customer Request (*as can be seen on the next step*).

Here’s an example how this integration looks like for your  `AndroidManifest` :

```xml
<intent-filter>
    <action android:name="android.intent.action.VIEW" />

    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <!-- Register the Cash Pay Kit redirect URI or URL. Change this accordingly in your app. -->
    <data
        android:scheme="cashapppay"
        android:host="checkout" />
  </intent-filter>
```

## Step 5: Create a Customer Request

You can create a Customer Request as soon as you know the amount you’d like to charge or if you'd like to create an on-file payment request. We suggest that you create this request as soon as your checkout view controller loads, so that your Customer can authorize the request without delay.

### Example of a One-Time Payment

To charge \$5.00 as a one-time payment, your `createrequest` call might look like this:

```kotlin
val redirectUri = "yourapp://return_path"

val oneTimePayment = OneTimeAction(currency = USD, amount = 123, scopeId = "YOUR SCOPE ID HERE")
cashAppPay.createCustomerRequest(oneTimePayment, redirectUri)
```

**Note**: If you're using Afterpay SDK together with Cash App Pay SDK, the `merchantId` contained within that data is the same as `scopeId` in this context.

### Example of an On-File Payment

```kotlin
val redirectUri = "yourapp://return_path"

val onFilePayment = OnFileAction(scopeId = "YOUR SCOPE ID HERE")
cashAppPay.createCustomerRequest(onFilePayment, redirectURI)
```

## Step 6: Authorize the Customer Request

Once the SDK is in the `ReadyToAuthorize` state, you can display the Cash App Pay button. When the Customer taps the button, you can authorize the Customer Request.

**Example**

```kotlin
cashAppPay.authorizeCustomerRequest()
```

> Currently, the Button provided by the SDK is unmanaged. This means that it's a stylized button which isn't aware of SDK events out-of-the-box. It is the developer's responsibility to call the above method when the button is clicked and also manage any disabled and loading states.

Your app will redirect to Cash App for authorization. When the authorization is completed, your redirect URI will be called to open your app. The SDK will fetch your authorized request and return it to your callback listener as one of 2 states: `Approved` or `Declined`.

## Step 7: Pass Grants to the Backend and Create Payment

The `Approved` state will contain a `Grants` list object associated with it and it can be used with Cash App's [Create Payment API](/cash-app-pay-partner-api/api-reference/network-api/create-payment). Pass these Grants to your backend and call the `CreatePayment` API as a server-to-server call to complete your payment.

***

---

# UI Components

The SDK provides an unmanaged custom view deriving from `Button`. There are separate Light and Dark versions to best match your particular UI, and the component is designed to allow for some flexibility in sizing (on both axes).

## CashAppPayButton

Developers are allowed to change the size of `CashAppPayButton` to suit their design, as long as they fall within certain limits.

These limits are:
`CashAppPayButton` should be:

* at least `34dp` tall
* at least `122dp` wide
* at most `54dp` tall

The light and dark variants of the `CashAppPayButton` can be defined using the style parameter, as follows:

```xml title= "Light Button"
<app.cash.paykit.core.ui.CashAppPayButton
      style="@style/CAPButtonStyle.Light"
      android:layout_height="54dp"
      android:layout_width="match_parent"
      />
```

<br />

**Light-background Button:**

<img width="331" alt="Light background Button" src="https://user-images.githubusercontent.com/416941/218883181-77ad30e7-f41a-42b0-a1a4-e829612828e7.png" noZoom />

<br />

```xml title= "Dark Button"
<app.cash.paykit.core.ui.CashAppPayButton
      style="@style/CAPButtonStyle.Dark"
      android:layout_height="54dp"
      android:layout_width="match_parent"
      />
```

<br />

**Dark-background Button:**

<img width="331" alt="Dark background Button" src="https://user-images.githubusercontent.com/416941/218883219-da3588d4-e674-48e2-8299-9c10b4558750.png" noZoom />

<Note>
  Due to its unmanaged nature, the button is merely a stylized button, it's up to developers to trigger the correct action on button press, as well as manage any visibility states of the button accordingly.
</Note>

<Note>
  You can use Android's Resource Qualifiers, such as `values-night`, to easily provide a button variation that follows the system's theme.
</Note>

## Pay Kit Android: Advanced Operations

This page describes advanced operations for the Cash App Pay Android SDK. For most setups, see [Getting Started](/cash-app-pay-partner-api/guides/pay-kit-sdk/pay-kit-android) first, which should contain most of the relevant information for your needs.

### Start with an existing customer request

When you use `createCustomerRequest` you get a `CustomerResponseData` object returned to you. This object contains an `id` field which is the `Request ID`.

<Note>
  If required, you can save this ID to retrieve the request at a later time.
</Note>

Since you are starting with an existing customer request, you'd start the SDK by calling `startWithExistingCustomerRequest` and pass the `Request ID`.

<br />This is how it would look:

```kotlin
cashAppPay.startWithExistingCustomerRequest(customerRequestID)
```

<br />

<Note title="Note">
  * You must call this function *only* when you start on a new SDK instance.
  * You must register for state updates before calling this function.
</Note>

### Update an existing customer request

You can update an existing customer request by calling `updateCustomerRequest` and passing in the `Request ID` and a new `CashAppPayPaymentAction` object.

<br />

This is the signature of the function:

```kotlin
fun updateCustomerRequest(
    requestId: String,
    paymentAction: CashAppPayPaymentAction,
)
```

<br />

<Note>
  You would typically use this function only after you've already started the SDK with a customer request.
</Note>

---

# List brands

GET https://api.cash.app/network/v1/brands

Returns a list of brands matching the given query parameters.

**This endpoint is rate limited to 50 QPS.**

Scopes: `BRANDS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-brands

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List brands
  version: endpoint_brands.list-brands
paths:
  /brands:
    get:
      operationId: list-brands
      summary: List brands
      description: |-
        Returns a list of brands matching the given query parameters.

        **This endpoint is rate limited to 50 QPS.**

        Scopes: `BRANDS_READ`
      tags:
        - - subpackage_brands
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of brands to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: reference_id
          in: query
          description: >-
            Filters results to only include brands with a `reference_id`
            matching the given value.
          required: false
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brands_list-brands_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    Metadata:
      type: object
      additionalProperties:
        type: string
    Brand:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the brand issued by Cash App.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        created_at:
          type: string
          format: date-time
          description: >-
            When this brand was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this brand was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system. 
            Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body).


            Min length: `1`

            Max length: `1024`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format (`#f0f0f0`).


            Min length: `7`

            Max length: `7`
        profile_image_url:
          type: string
          format: uri
          default: >-
            https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable file formats:

            - `.png`

            - `.jpg`

            - `.jpeg`


            Min length: `8`

            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - name
        - created_at
        - updated_at
        - reference_id
    Brands_list-brands_Response_200:
      type: object
      properties:
        brands:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
          description: List of brands matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - brands

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/brands"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/brands")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/brands', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create brand

POST https://api.cash.app/network/v1/brands
Content-Type: application/json

Creates a new brand with the given attributes.

**This endpoint is not rate limited.**

Scopes: `BRANDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-brand

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create brand
  version: endpoint_brands.create-brand
paths:
  /brands:
    post:
      operationId: create-brand
      summary: Create brand
      description: |-
        Creates a new brand with the given attributes.

        **This endpoint is not rate limited.**

        Scopes: `BRANDS_WRITE`
      tags:
        - - subpackage_brands
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brands_create-brand_Response_201'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                brand:
                  $ref: >-
                    #/components/schemas/BrandsPostRequestBodyContentApplicationJsonSchemaBrand
                  description: Details about the brand to create.
              required:
                - idempotency_key
                - brand
components:
  schemas:
    IdempotencyKey:
      type: string
    Metadata:
      type: object
      additionalProperties:
        type: string
    BrandsPostRequestBodyContentApplicationJsonSchemaBrand:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system.


            **Must be unique across all brands. Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body)**


            Min length: `1`

            Max length: `1024`
        profile_image_url:
          type: string
          format: uri
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable image formats:

            - `png`

            - `jpg`

            - `jpeg`


            Min length: `8`

            Max length: `8000`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format.


            Pattern: `^#[a-fA-F0-9]{6}$`

            Min length: `7`

            Max length: `7`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - name
        - reference_id
    Brand:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the brand issued by Cash App.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        created_at:
          type: string
          format: date-time
          description: >-
            When this brand was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this brand was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system. 
            Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body).


            Min length: `1`

            Max length: `1024`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format (`#f0f0f0`).


            Min length: `7`

            Max length: `7`
        profile_image_url:
          type: string
          format: uri
          default: >-
            https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable file formats:

            - `.png`

            - `.jpg`

            - `.jpeg`


            Min length: `8`

            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - name
        - created_at
        - updated_at
        - reference_id
    Brands_create-brand_Response_201:
      type: object
      properties:
        brand:
          $ref: '#/components/schemas/Brand'

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/brands"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff",
        "metadata": { "key": "value" }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/brands")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": ["key": "value"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/brands"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff",
        "metadata": { "key": "value" }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/brands")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": ["key": "value"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Upsert brand

PUT https://api.cash.app/network/v1/brands
Content-Type: application/json

Creates or updates a brand based on the brand's `reference_id`.

If a brand with a matching `reference_id` is found, 
it will be updated. Ensure proper mapping; if no matching brand is found, 
a new one will be created. 

The HTTP response code (`200 OK` or `201 Created`) indicates
whether the resource was updated or created, respectively.

<Note>

 `brand_id` is the primary unique identifier for all Brand APIs.
 Be cautious when using `reference_id` as a unique identifier. 
</Note>

**This endpoint is not rate limited.**

Scopes: `BRANDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/upsert-brand

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Upsert brand
  version: endpoint_brands.upsert-brand
paths:
  /brands:
    put:
      operationId: upsert-brand
      summary: Upsert brand
      description: >-
        Creates or updates a brand based on the brand's `reference_id`.


        If a brand with a matching `reference_id` is found, 

        it will be updated. Ensure proper mapping; if no matching brand is
        found, 

        a new one will be created. 


        The HTTP response code (`200 OK` or `201 Created`) indicates

        whether the resource was updated or created, respectively.


        <Note>

         `brand_id` is the primary unique identifier for all Brand APIs.
         Be cautious when using `reference_id` as a unique identifier. 
        </Note>


        **This endpoint is not rate limited.**


        Scopes: `BRANDS_WRITE`
      tags:
        - - subpackage_brands
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brands_upsert-brand_Response_200'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                brand:
                  $ref: >-
                    #/components/schemas/BrandsPutRequestBodyContentApplicationJsonSchemaBrand
                  description: Details about the brand to create or update.
              required:
                - brand
components:
  schemas:
    Metadata:
      type: object
      additionalProperties:
        type: string
    BrandsPutRequestBodyContentApplicationJsonSchemaBrand:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system.


            **Must be unique across all brands.  Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body)**


            Min length: `1`

            Max length: `1024`
        profile_image_url:
          type: string
          format: uri
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable image formats:

            - `png`

            - `jpg`

            - `jpeg`


            Min length: `8`

            Max length: `8000`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format.


            Pattern: `^#[a-fA-F0-9]{6}$`

            Min length: `7`

            Max length: `7`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - name
        - reference_id
    Brand:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the brand issued by Cash App.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        created_at:
          type: string
          format: date-time
          description: >-
            When this brand was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this brand was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system. 
            Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body).


            Min length: `1`

            Max length: `1024`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format (`#f0f0f0`).


            Min length: `7`

            Max length: `7`
        profile_image_url:
          type: string
          format: uri
          default: >-
            https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable file formats:

            - `.png`

            - `.jpg`

            - `.jpeg`


            Min length: `8`

            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - name
        - created_at
        - updated_at
        - reference_id
    Brands_upsert-brand_Response_200:
      type: object
      properties:
        brand:
          $ref: '#/components/schemas/Brand'

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/brands"

payload = { "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff"
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/brands")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff"
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/brands"

payload = { "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff",
        "metadata": { "key": "value" }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/brands")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": ["key": "value"]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/brands"

payload = { "brand": {
        "name": "brand name",
        "reference_id": "reference ID",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff",
        "metadata": { "key": "value" }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"brand":{"name":"brand name","reference_id":"reference ID","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/brands")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/brands', [
  'body' => '{
  "brand": {
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"brand name\",\n    \"reference_id\": \"reference ID\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["brand": [
    "name": "brand name",
    "reference_id": "reference ID",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": ["key": "value"]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve brand

GET https://api.cash.app/network/v1/brands/{brand_id}

Returns a brand matching the given `brand_id`.

**This endpoint is not rate limited.**

Scopes: `BRANDS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-brand

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve brand
  version: endpoint_brands.retrieve-brand
paths:
  /brands/{brand_id}:
    get:
      operationId: retrieve-brand
      summary: Retrieve brand
      description: |-
        Returns a brand matching the given `brand_id`.

        **This endpoint is not rate limited.**

        Scopes: `BRANDS_READ`
      tags:
        - - subpackage_brands
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brands_retrieve-brand_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Metadata:
      type: object
      additionalProperties:
        type: string
    Brand:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the brand issued by Cash App.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        created_at:
          type: string
          format: date-time
          description: >-
            When this brand was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this brand was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system. 
            Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body).


            Min length: `1`

            Max length: `1024`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format (`#f0f0f0`).


            Min length: `7`

            Max length: `7`
        profile_image_url:
          type: string
          format: uri
          default: >-
            https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable file formats:

            - `.png`

            - `.jpg`

            - `.jpeg`


            Min length: `8`

            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - name
        - created_at
        - updated_at
        - reference_id
    Brands_retrieve-brand_Response_200:
      type: object
      properties:
        brand:
          $ref: '#/components/schemas/Brand'
      required:
        - brand

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/brands/brand_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/brands/brand_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands/brand_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands/brand_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/brands/brand_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/brands/brand_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/brands/brand_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands/brand_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Update brand

PATCH https://api.cash.app/network/v1/brands/{brand_id}
Content-Type: application/json

Updates a brand matching the provided `brand_id` with the given attributes.

To clear a field, set it to `null`. Fields that are not provided in the request will not be changed.

**This endpoint is not rate limited.**

Scopes: `BRANDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/update-brand

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update brand
  version: endpoint_brands.update-brand
paths:
  /brands/{brand_id}:
    patch:
      operationId: update-brand
      summary: Update brand
      description: >-
        Updates a brand matching the provided `brand_id` with the given
        attributes.


        To clear a field, set it to `null`. Fields that are not provided in the
        request will not be changed.


        **This endpoint is not rate limited.**


        Scopes: `BRANDS_WRITE`
      tags:
        - - subpackage_brands
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Brands_update-brand_Response_200'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                brand:
                  $ref: >-
                    #/components/schemas/BrandsBrandIdPatchRequestBodyContentApplicationJsonSchemaBrand
                  description: Details about the brand to update
              required:
                - brand
components:
  schemas:
    Metadata:
      type: object
      additionalProperties:
        type: string
    BrandsBrandIdPatchRequestBodyContentApplicationJsonSchemaBrand:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            *This field cannot be cleared.*

            Min length: `1`
            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system. 
            Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body).


            *This field cannot be cleared, and must be unique across all
            brands.*


            Min length: `1`

            Max length: `1024`
        profile_image_url:
          type: string
          format: uri
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable image formats:

            - `png`

            - `jpg`

            - `jpeg`


            *This field cannot be cleared.*


            Min length: `8`

            Max length: `8000`
        color:
          type:
            - string
            - 'null'
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format.


            Pattern: `^#[a-fA-F0-9]{6}$`

            Min length: `7`

            Max length: `7`
        metadata:
          $ref: '#/components/schemas/Metadata'
    Brand:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the brand issued by Cash App.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        created_at:
          type: string
          format: date-time
          description: >-
            When this brand was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this brand was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this brand, typically used to
            associate the brand with a record in an external system. 
            Independent from the [merchant
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-merchant#request-body).


            Min length: `1`

            Max length: `1024`
        color:
          type: string
          description: >-
            Primary color associated with this brand and its logo, in 6-digit
            hex code format (`#f0f0f0`).


            Min length: `7`

            Max length: `7`
        profile_image_url:
          type: string
          format: uri
          default: >-
            https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png
          description: >-
            URL to the image that should be shown in Cash App next to payments
            made to this brand, typically the brand's logo.


            The image should be square and be at least 256x256. It must be less
            than 2MB in filesize.


            Acceptable file formats:

            - `.png`

            - `.jpg`

            - `.jpeg`


            Min length: `8`

            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - name
        - created_at
        - updated_at
        - reference_id
    Brands_update-brand_Response_200:
      type: object
      properties:
        brand:
          $ref: '#/components/schemas/Brand'

```

## SDK Code Examples

```python Example
import requests

url = "https://api.cash.app/network/v1/brands/brand_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, headers=headers)

print(response.json())
```

```javascript Example
const url = 'https://api.cash.app/network/v1/brands/brand_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands/brand_id"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands/brand_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Example
HttpResponse<String> response = Unirest.patch("https://api.cash.app/network/v1/brands/brand_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Example
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/network/v1/brands/brand_id', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Example
var client = new RestClient("https://api.cash.app/network/v1/brands/brand_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands/brand_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Sample request with metadata
import requests

url = "https://api.cash.app/network/v1/brands/brand_id"

payload = { "brand": {
        "name": "Out of this World",
        "reference_id": "external-id",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff",
        "metadata": { "key": "value" }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Sample request with metadata
const url = 'https://api.cash.app/network/v1/brands/brand_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"brand":{"name":"Out of this World","reference_id":"external-id","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Sample request with metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands/brand_id"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Sample request with metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands/brand_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Sample request with metadata
HttpResponse<String> response = Unirest.patch("https://api.cash.app/network/v1/brands/brand_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php Sample request with metadata
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/network/v1/brands/brand_id', [
  'body' => '{
  "brand": {
    "name": "Out of this World",
    "reference_id": "external-id",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Sample request with metadata
var client = new RestClient("https://api.cash.app/network/v1/brands/brand_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request with metadata
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["brand": [
    "name": "Out of this World",
    "reference_id": "external-id",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff",
    "metadata": ["key": "value"]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands/brand_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Sample request without metadata
import requests

url = "https://api.cash.app/network/v1/brands/brand_id"

payload = { "brand": {
        "name": "Out of this World",
        "reference_id": "external-id",
        "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
        "color": "#ffffff"
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Sample request without metadata
const url = 'https://api.cash.app/network/v1/brands/brand_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"brand":{"name":"Out of this World","reference_id":"external-id","profile_image_url":"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg","color":"#ffffff"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Sample request without metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/brands/brand_id"

	payload := strings.NewReader("{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Sample request without metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/brands/brand_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Sample request without metadata
HttpResponse<String> response = Unirest.patch("https://api.cash.app/network/v1/brands/brand_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}")
  .asString();
```

```php Sample request without metadata
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/network/v1/brands/brand_id', [
  'body' => '{
  "brand": {
    "name": "Out of this World",
    "reference_id": "external-id",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff"
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Sample request without metadata
var client = new RestClient("https://api.cash.app/network/v1/brands/brand_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"brand\": {\n    \"name\": \"Out of this World\",\n    \"reference_id\": \"external-id\",\n    \"profile_image_url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg\",\n    \"color\": \"#ffffff\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request without metadata
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["brand": [
    "name": "Out of this World",
    "reference_id": "external-id",
    "profile_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Earth_from_Space.jpg/480px-Earth_from_Space.jpg",
    "color": "#ffffff"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/brands/brand_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Brand

<EndpointSchemaSnippet endpoint="PATCH /brands/:brand_id" selector="response" />

<Aside>
  ```json Example
  {
    "id": "string",
    "name": "string",
    "created_at": "2021-01-01T00:00:00Z",
    "updated_at": "2021-01-01T00:00:00Z",
    "reference_id": "example-id",
    "color": "#ffffff",
    "profile_image_url": "https://franklin-assets.s3.amazonaws.com/merchants/assets/v3/generic/m_category_business.png",
    "metadata": {
      "my-meta": "meta-value"
    }
  }
  ```
</Aside>

---

# List merchants

GET https://api.cash.app/network/v1/merchants

Returns a list of merchants matching the given query parameters.

**This endpoint is rate limited to 50 QPS.**

Scopes: `MERCHANTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-merchants

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List merchants
  version: endpoint_merchants.list-merchants
paths:
  /merchants:
    get:
      operationId: list-merchants
      summary: List merchants
      description: |-
        Returns a list of merchants matching the given query parameters.

        **This endpoint is rate limited to 50 QPS.**

        Scopes: `MERCHANTS_READ`
      tags:
        - - subpackage_merchants
      parameters:
        - name: reference_id
          in: query
          description: >-
            Filters results to only include merchants with a `reference_id`
            matching the given value.
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of merchants to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchants_list-merchants_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Category:
      type: string
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    Merchants_list-merchants_Response_200:
      type: object
      properties:
        merchants:
          type: array
          items:
            $ref: '#/components/schemas/Merchant'
          description: List of merchants matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - merchants

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/merchants"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/merchants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/merchants', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create merchant

POST https://api.cash.app/network/v1/merchants
Content-Type: application/json

Creates a new merchant. Merchants must have an `address` or `site_url` set.

**This endpoint is not rate limited.**

Scopes: `MERCHANTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-merchant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create merchant
  version: endpoint_merchants.create-merchant
paths:
  /merchants:
    post:
      operationId: create-merchant
      summary: Create merchant
      description: >-
        Creates a new merchant. Merchants must have an `address` or `site_url`
        set.


        **This endpoint is not rate limited.**


        Scopes: `MERCHANTS_WRITE`
      tags:
        - - subpackage_merchants
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchants_create-merchant_Response_201'
        '400':
          description: Bad Request
          content: {}
        '409':
          description: Conflict
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                merchant:
                  $ref: >-
                    #/components/schemas/MerchantsPostRequestBodyContentApplicationJsonSchemaMerchant
                  description: Details about the merchant to create.
              required:
                - idempotency_key
                - merchant
components:
  schemas:
    IdempotencyKey:
      type: string
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Category:
      type: string
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    MerchantsPostRequestBodyContentApplicationJsonSchemaMerchant:
      type: object
      properties:
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        brand_id:
          type: string
          description: |
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.


            **Must be unique across all merchants. Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body)**


            Min length: `1`

            Max length: `1024`
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - name
        - brand_id
        - country
        - currency
        - category
        - reference_id
        - address
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    Merchants_create-merchant_Response_201:
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/Merchant'
      required:
        - merchant

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/merchants"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "merchant": {
        "name": "merchant name",
        "brand_id": "brand ID",
        "country": "US",
        "currency": "USD",
        "category": "5432",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "https://example.com",
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","merchant":{"name":"merchant name","brand_id":"brand ID","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"https://example.com","default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/merchants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/merchants', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "merchant": {
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "https://example.com",
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "merchant": [
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "https://example.com",
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/merchants"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "merchant": {
        "name": "merchant name",
        "brand_id": "brand ID",
        "country": "US",
        "currency": "USD",
        "category": "5432",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "https://example.com",
        "metadata": { "key": "value" },
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","merchant":{"name":"merchant name","brand_id":"brand ID","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"https://example.com","metadata":{"key":"value"},"default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/merchants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/merchants', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "merchant": {
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "https://example.com",
    "metadata": {
      "key": "value"
    },
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "merchant": [
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "https://example.com",
    "metadata": ["key": "value"],
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Upsert merchant

PUT https://api.cash.app/network/v1/merchants
Content-Type: application/json

Creates or updates a merchant based on the merchant's `reference_id`.

If a merchant with a matching `reference_id` is found, 
it will be updated. If no matching merchant is found,
a new one will be created.

The HTTP response code (`200 OK` or `201 Created`) indicates
whether the resource was updated or created, respectively.

<Info>

 `merchant_id` is the primary unique identifier for all Merchant APIs.
 Be cautious when using `reference_id` as a unique identifier.
 
 Merchants must have an `address` or `site_url` set.
</Info>  

**This endpoint is not rate limited.**

Scopes: `MERCHANTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/upsert-merchant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Upsert merchant
  version: endpoint_merchants.upsert-merchant
paths:
  /merchants:
    put:
      operationId: upsert-merchant
      summary: Upsert merchant
      description: |-
        Creates or updates a merchant based on the merchant's `reference_id`.

        If a merchant with a matching `reference_id` is found, 
        it will be updated. If no matching merchant is found,
        a new one will be created.

        The HTTP response code (`200 OK` or `201 Created`) indicates
        whether the resource was updated or created, respectively.

        <Info>

         `merchant_id` is the primary unique identifier for all Merchant APIs.
         Be cautious when using `reference_id` as a unique identifier.
         
         Merchants must have an `address` or `site_url` set.
        </Info>  

        **This endpoint is not rate limited.**

        Scopes: `MERCHANTS_WRITE`
      tags:
        - - subpackage_merchants
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchants_upsert-merchant_Response_200'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchant:
                  $ref: >-
                    #/components/schemas/MerchantsPutRequestBodyContentApplicationJsonSchemaMerchant
                  description: Details about the merchant to create or update.
              required:
                - merchant
components:
  schemas:
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Category:
      type: string
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    MerchantsPutRequestBodyContentApplicationJsonSchemaMerchant:
      type: object
      properties:
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.


            **Must be unique across all merchants. Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).**


            Min length: `1`

            Max length: `1024`
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - name
        - brand_id
        - country
        - currency
        - category
        - reference_id
        - address
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    Merchants_upsert-merchant_Response_200:
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/Merchant'
      required:
        - merchant

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/merchants"

payload = { "merchant": {
        "name": "merchant name",
        "brand_id": "brand ID",
        "country": "US",
        "currency": "USD",
        "category": "5432",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "http://example.com",
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"merchant":{"name":"merchant name","brand_id":"brand ID","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"http://example.com","default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants"

	payload := strings.NewReader("{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/merchants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/merchants', [
  'body' => '{
  "merchant": {
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "http://example.com",
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["merchant": [
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "http://example.com",
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/merchants"

payload = { "merchant": {
        "name": "merchant name",
        "brand_id": "brand ID",
        "country": "US",
        "currency": "USD",
        "category": "5432",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "http://example.com",
        "metadata": { "key": "value" },
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"merchant":{"name":"merchant name","brand_id":"brand ID","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"http://example.com","metadata":{"key":"value"},"default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants"

	payload := strings.NewReader("{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/merchants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/merchants', [
  'body' => '{
  "merchant": {
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "http://example.com",
    "metadata": {
      "key": "value"
    },
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["merchant": [
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "http://example.com",
    "metadata": ["key": "value"],
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/merchants"

payload = { "merchant": {
        "name": "merchant name",
        "brand_id": "brand ID",
        "country": "US",
        "currency": "USD",
        "category": "5432",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "http://example.com",
        "metadata": { "key": "value" },
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants';
const options = {
  method: 'PUT',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"merchant":{"name":"merchant name","brand_id":"brand ID","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"http://example.com","metadata":{"key":"value"},"default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants"

	payload := strings.NewReader("{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.put("https://api.cash.app/network/v1/merchants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.cash.app/network/v1/merchants', [
  'body' => '{
  "merchant": {
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "http://example.com",
    "metadata": {
      "key": "value"
    },
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchant\": {\n    \"name\": \"merchant name\",\n    \"brand_id\": \"brand ID\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"category\": \"5432\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"http://example.com\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["merchant": [
    "name": "merchant name",
    "brand_id": "brand ID",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "http://example.com",
    "metadata": ["key": "value"],
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve merchant

GET https://api.cash.app/network/v1/merchants/{merchant_id}

Returns a merchant matching the given `merchant_id`.

**This endpoint is not rate limited.**

Scopes: `MERCHANTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-merchant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve merchant
  version: endpoint_merchants.retrieve-merchant
paths:
  /merchants/{merchant_id}:
    get:
      operationId: retrieve-merchant
      summary: Retrieve merchant
      description: |-
        Returns a merchant matching the given `merchant_id`.

        **This endpoint is not rate limited.**

        Scopes: `MERCHANTS_READ`
      tags:
        - - subpackage_merchants
      parameters:
        - name: merchant_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchants_retrieve-merchant_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Category:
      type: string
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    Merchants_retrieve-merchant_Response_200:
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/Merchant'
      required:
        - merchant

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/merchants/merchant_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants/merchant_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants/merchant_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants/merchant_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/merchants/merchant_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/merchants/merchant_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants/merchant_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants/merchant_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Update merchant

PATCH https://api.cash.app/network/v1/merchants/{merchant_id}
Content-Type: application/json

Updates a merchant matching the provided `merchant_id` with the given attributes.

To clear a field, set it to `null`. Fields that are not provided in the request will not be changed.

**This endpoint is not rate limited.**

Scopes: `MERCHANTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/update-merchant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update merchant
  version: endpoint_merchants.update-merchant
paths:
  /merchants/{merchant_id}:
    patch:
      operationId: update-merchant
      summary: Update merchant
      description: >-
        Updates a merchant matching the provided `merchant_id` with the given
        attributes.


        To clear a field, set it to `null`. Fields that are not provided in the
        request will not be changed.


        **This endpoint is not rate limited.**


        Scopes: `MERCHANTS_WRITE`
      tags:
        - - subpackage_merchants
      parameters:
        - name: merchant_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchants_update-merchant_Response_200'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                merchant:
                  $ref: >-
                    #/components/schemas/MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchant
                  description: Details about the merchant to update.
              required:
                - merchant
components:
  schemas:
    Category:
      type: string
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CLIENT_DISABLED
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchant:
      type: object
      properties:
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            *This field cannot be cleared.*

            Min length: `1`
            Max length: `128`
        category:
          $ref: '#/components/schemas/Category'
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            *This field cannot be cleared.*


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            *This field cannot be cleared, and must be unique across all
            merchants.*


            Min length: `1`

            Max length: `1024`
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type:
            - string
            - 'null'
          format: uri
          description: |-
            The URL of the website, if this merchant is an eCommerce site.

            Min length: `8`
            Max length: `8000`
        status:
          $ref: >-
            #/components/schemas/MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchantStatus
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            **Note:** when the value is `PENDING`, `COMPLIANCE_DISABLED`, or
            `RISK_DISABLED`, the status of the merchant cannot be changed.


            Current values:

            - `ACTIVE`: The merchant can accept payments and issue refunds.

            - `CLIENT_DISABLED`: The merchant has been disabled by the API
            client, and may be re-enabled by the API client at any time.
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    Merchants_update-merchant_Response_200:
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/Merchant'

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/merchants/merchant_id"

payload = { "merchant": {
        "brand_id": "brand ID",
        "category": "5432",
        "country": "US",
        "currency": "USD",
        "name": "merchant name",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "https://example.com",
        "status": "ACTIVE",
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants/merchant_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"merchant":{"brand_id":"brand ID","category":"5432","country":"US","currency":"USD","name":"merchant name","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"https://example.com","status":"ACTIVE","default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants/merchant_id"

	payload := strings.NewReader("{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants/merchant_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.cash.app/network/v1/merchants/merchant_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/network/v1/merchants/merchant_id', [
  'body' => '{
  "merchant": {
    "brand_id": "brand ID",
    "category": "5432",
    "country": "US",
    "currency": "USD",
    "name": "merchant name",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "https://example.com",
    "status": "ACTIVE",
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants/merchant_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["merchant": [
    "brand_id": "brand ID",
    "category": "5432",
    "country": "US",
    "currency": "USD",
    "name": "merchant name",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "https://example.com",
    "status": "ACTIVE",
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants/merchant_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/merchants/merchant_id"

payload = { "merchant": {
        "brand_id": "brand ID",
        "category": "5432",
        "country": "US",
        "currency": "USD",
        "name": "merchant name",
        "reference_id": "reference ID",
        "address": {
            "country": "US",
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
        },
        "site_url": "https://example.com",
        "status": "ACTIVE",
        "metadata": { "key": "value" },
        "default_fee_plans": {
            "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
            "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
        }
    } }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/merchants/merchant_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"merchant":{"brand_id":"brand ID","category":"5432","country":"US","currency":"USD","name":"merchant name","reference_id":"reference ID","address":{"country":"US","address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"site_url":"https://example.com","status":"ACTIVE","metadata":{"key":"value"},"default_fee_plans":{"in_app_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","in_person_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me","online_fee_plan_id":"FEE_kewjsmjt35t8qhzyjeqcst5me"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/merchants/merchant_id"

	payload := strings.NewReader("{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/merchants/merchant_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.cash.app/network/v1/merchants/merchant_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/network/v1/merchants/merchant_id', [
  'body' => '{
  "merchant": {
    "brand_id": "brand ID",
    "category": "5432",
    "country": "US",
    "currency": "USD",
    "name": "merchant name",
    "reference_id": "reference ID",
    "address": {
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "https://example.com",
    "status": "ACTIVE",
    "metadata": {
      "key": "value"
    },
    "default_fee_plans": {
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/merchants/merchant_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchant\": {\n    \"brand_id\": \"brand ID\",\n    \"category\": \"5432\",\n    \"country\": \"US\",\n    \"currency\": \"USD\",\n    \"name\": \"merchant name\",\n    \"reference_id\": \"reference ID\",\n    \"address\": {\n      \"country\": \"US\",\n      \"address_line_1\": \"1215 4th Ave\",\n      \"address_line_2\": \"Suite 2300\",\n      \"locality\": \"Seattle\",\n      \"postal_code\": \"98161-1001\",\n      \"administrative_district_level_1\": \"Washington\"\n    },\n    \"site_url\": \"https://example.com\",\n    \"status\": \"ACTIVE\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"default_fee_plans\": {\n      \"in_app_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"in_person_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\",\n      \"online_fee_plan_id\": \"FEE_kewjsmjt35t8qhzyjeqcst5me\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["merchant": [
    "brand_id": "brand ID",
    "category": "5432",
    "country": "US",
    "currency": "USD",
    "name": "merchant name",
    "reference_id": "reference ID",
    "address": [
      "country": "US",
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    ],
    "site_url": "https://example.com",
    "status": "ACTIVE",
    "metadata": ["key": "value"],
    "default_fee_plans": [
      "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
      "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/merchants/merchant_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Merchant

<EndpointSchemaSnippet endpoint="POST /merchants" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "brand_id": "BRAND_8ereg0tug2yiik8vx24xpe5br",
    "name": "Example Business Name",
    "country": "US",
    "currency": "USD",
    "category": "5432",
    "reference_id": "external-id",
    "status": "ACTIVE",
    "created_at": "2022-01-01T12:00:00Z",
    "updated_at": "2022-01-05T12:00:00Z",
    "address": {
      "address_line_1": "1215 4th Ave",
      "address_line_2": "Suite 2300",
      "locality": "Seattle",
      "country": "US",
      "postal_code": "98161-1001",
      "administrative_district_level_1": "Washington"
    },
    "site_url": "http://example.com",
    "metadata": {}
  }
  ```
</Aside>

---

# Event: merchant.status.updated

POST 

**When is this event triggered?**

This event is created whenever a merchant's status is changed. The status change can be due to do many different things:
  - An API client-initiated action to disable / enable the merchant
  - An asynchronous merchant registration process completing, moving the merchant from pending to active
  - A compliance ban on the merchant, moving them to disabled

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/merchant-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: merchant.status.updated'
  version: subpackage_merchants.merchantStatusUpdated
webhooks:
  merchant-status-updated:
    post:
      operationId: merchant-status-updated
      summary: 'Event: merchant.status.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a merchant's status is changed. The
        status change can be due to do many different things:
          - An API client-initiated action to disable / enable the merchant
          - An asynchronous merchant registration process completing, moving the merchant from pending to active
          - A compliance ban on the merchant, moving them to disabled
      tags:
        - subpackage_merchants
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `merchant.status.updated`
                    for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the merchant that had a status change.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Category:
      type: string
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/Merchant'
      required:
        - merchant
    WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the merchant.
        object:
          $ref: >-
            #/components/schemas/WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the merchant data immediately after the merchant's
            status changed.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `merchant`.
      required:
        - id
        - object
        - type

```

---

# MerchantFeePlans

<EndpointSchemaSnippet endpoint="GET /merchant-fee-plans" selector="response.body" />

<Aside>
  ```json Example
  {
    "in_app_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
    "in_person_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
    "online_fee_plan_id": "FEE_kewjsmjt35t8qhzyjeqcst5me"
  }
  ```
</Aside>

---

# List customers

GET https://api.cash.app/network/v1/customers

Returns a list of all customers matching the given query parameters who have ever authorized this client to take an action on their account.

**This endpoint is rate limited to 50 QPS.**

Scopes: `CUSTOMERS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-customers

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List customers
  version: endpoint_customers.list-customers
paths:
  /customers:
    get:
      operationId: list-customers
      summary: List customers
      description: >-
        Returns a list of all customers matching the given query parameters who
        have ever authorized this client to take an action on their account.


        **This endpoint is rate limited to 50 QPS.**


        Scopes: `CUSTOMERS_READ`
      tags:
        - - subpackage_customers
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of customers to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: cashtag
          in: query
          description: Filters results to only include customers with a matching Cashtag.
          required: false
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customers_list-customers_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this customer, typically used to
            associate the customer with a record in an external system. This
            value can be provided via the
            `CustomerRequest.customer_metadata.reference_id` attribute. Upon
            approval of the CustomerRequest, a corresponding customer resource
            is created with the `reference_id` attribute.
      required:
        - id
        - cashtag
    Customers_list-customers_Response_200:
      type: object
      properties:
        customers:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
          description: List of customers matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - customers

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/customers"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/customers';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/customers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/customers")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/customers', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/customers");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/customers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve customer

GET https://api.cash.app/network/v1/customers/{customer_id}

Retrieves a customer by its ID.

**This endpoint is not rate limited.**

Scopes: `CUSTOMERS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve customer
  version: endpoint_customers.retrieve-customer
paths:
  /customers/{customer_id}:
    get:
      operationId: retrieve-customer
      summary: Retrieve customer
      description: |-
        Retrieves a customer by its ID.

        **This endpoint is not rate limited.**

        Scopes: `CUSTOMERS_READ`
      tags:
        - - subpackage_customers
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customers_retrieve-customer_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this customer, typically used to
            associate the customer with a record in an external system. This
            value can be provided via the
            `CustomerRequest.customer_metadata.reference_id` attribute. Upon
            approval of the CustomerRequest, a corresponding customer resource
            is created with the `reference_id` attribute.
      required:
        - id
        - cashtag
    Customers_retrieve-customer_Response_200:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
      required:
        - customer

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/customers/customer_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/customers/customer_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/customers/customer_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/customers/customer_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/customers/customer_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/customers/customer_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/customers/customer_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/customers/customer_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve customer grant

GET https://api.cash.app/network/v1/customers/{customer_id}/grants/{grant_id}

Retrieves a customer grant by the ID of the customer that approved it and its own ID.

**This endpoint is not rate limited.**

Scopes: `GRANTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-customer-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve customer grant
  version: endpoint_customers.retrieve-customer-grant
paths:
  /customers/{customer_id}/grants/{grant_id}:
    get:
      operationId: retrieve-customer-grant
      summary: Retrieve customer grant
      description: >-
        Retrieves a customer grant by the ID of the customer that approved it
        and its own ID.


        **This endpoint is not rate limited.**


        Scopes: `GRANTS_READ`
      tags:
        - - subpackage_customers
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: grant_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Customers_retrieve-customer-grant_Response_200
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    Customers_retrieve-customer-grant_Response_200:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/customers/customer_id/grants/grant_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/customers/customer_id/grants/grant_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/customers/customer_id/grants/grant_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/customers/customer_id/grants/grant_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/customers/customer_id/grants/grant_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/customers/customer_id/grants/grant_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/customers/customer_id/grants/grant_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/customers/customer_id/grants/grant_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# List customer grants

GET https://api.cash.app/network/v1/customers/{customer_id}/grants

Returns a list of all customer grants for a given customer that match the provided query parameters.

**This endpoint is rate limited to 250 QPS.**

Scopes: `GRANTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-customer-grants

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List customer grants
  version: endpoint_customers.list-customer-grants
paths:
  /customers/{customer_id}/grants:
    get:
      operationId: list-customer-grants
      summary: List customer grants
      description: >-
        Returns a list of all customer grants for a given customer that match
        the provided query parameters.


        **This endpoint is rate limited to 250 QPS.**


        Scopes: `GRANTS_READ`
      tags:
        - - subpackage_customers
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of customer grants to return
          required: false
          schema:
            type: integer
            default: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Customers_list-customer-grants_Response_200
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    Customers_list-customer-grants_Response_200:
      type: object
      properties:
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: List of customer grants matching the given query parameters
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - grants

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/customers/customer_id/grants"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/customers/customer_id/grants';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/customers/customer_id/grants"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/customers/customer_id/grants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/customers/customer_id/grants")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/customers/customer_id/grants', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/customers/customer_id/grants");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/customers/customer_id/grants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Revoke customer grant

POST https://api.cash.app/network/v1/customers/{customer_id}/grants/{grant_id}/revoke

Revokes a customer grant, rendering it unusable. Other endpoints will no longer be able to use the grant to perform its associated action.

<Note> 
You cannot un-revoke a grant. Use with caution.
</Note>

**This endpoint is not rate limited.**

Scopes: `GRANTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/revoke-customer-grant

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Revoke customer grant
  version: endpoint_customers.revoke-customer-grant
paths:
  /customers/{customer_id}/grants/{grant_id}/revoke:
    post:
      operationId: revoke-customer-grant
      summary: Revoke customer grant
      description: >-
        Revokes a customer grant, rendering it unusable. Other endpoints will no
        longer be able to use the grant to perform its associated action.


        <Note> 

        You cannot un-revoke a grant. Use with caution.

        </Note>


        **This endpoint is not rate limited.**


        Scopes: `GRANTS_WRITE`
      tags:
        - - subpackage_customers
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: grant_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Customers_revoke-customer-grant_Response_200
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    Customers_revoke-customer-grant_Response_200:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/customers/customer_id/grants/grant_id/revoke")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Customer

<EndpointSchemaSnippet endpoint="GET /customer-schema" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "cashtag": "string",
    "reference_id": "CUST_123"
  }
  ```
</Aside>

---

# Event: grant.created

POST 

**When is this event triggered?**

This event is created whenever a grant is created. This is caused by a customer request being approved.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/grant-created

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: grant.created'
  version: subpackage_customers.grantCreated
webhooks:
  grant-created:
    post:
      operationId: grant-created
      summary: 'Event: grant.created'
      description: >-
        **When is this event triggered?**


        This event is created whenever a grant is created. This is caused by a
        customer request being approved.
      tags:
        - subpackage_customers
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `grant.created` for this
                    event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksGrantCreatedPayloadContentApplicationJsonSchemaData
                  description: Data about the grant that was created.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    WebhooksGrantCreatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant
    WebhooksGrantCreatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the grant.
        object:
          $ref: >-
            #/components/schemas/WebhooksGrantCreatedPayloadContentApplicationJsonSchemaDataObject
          description: A snapshot of the grant immediately after the grant was created.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `grant`.
      required:
        - id
        - object
        - type

```

---

# Event: grant.status.updated

POST 

**When is this event triggered?**

This event is created whenever a grant's status is changed. The status change can be due to a couple different things:
  - An API client-initiated action to create a payment or revoke a grant (all opertions which consume a one-time use grant)
  - A customer revoking an extended-use grant

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/grant-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: grant.status.updated'
  version: subpackage_customers.grantStatusUpdated
webhooks:
  grant-status-updated:
    post:
      operationId: grant-status-updated
      summary: 'Event: grant.status.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a grant's status is changed. The status
        change can be due to a couple different things:
          - An API client-initiated action to create a payment or revoke a grant (all opertions which consume a one-time use grant)
          - A customer revoking an extended-use grant
      tags:
        - subpackage_customers
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `grant.status.updated` for
                    this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the grant that had a status change.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
      required:
        - grant
    WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the grant.
        object:
          $ref: >-
            #/components/schemas/WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the grant immediately after the grant's status
            changed.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `grant`.
      required:
        - id
        - object
        - type

```

---

# Event: customer.created

POST 

**When is this event triggered?**

This event is created whenever a new Cash App Pay customer is created. A new Cash App Pay customer is created when a Cash App user approves a client's Cash App Pay request for the first time. This event allows clients to detect customers who are using a client's Cash App Pay integration for the first time.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/customer-created

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: customer.created'
  version: subpackage_customers.customerCreated
webhooks:
  customer-created:
    post:
      operationId: customer-created
      summary: 'Event: customer.created'
      description: >-
        **When is this event triggered?**


        This event is created whenever a new Cash App Pay customer is created. A
        new Cash App Pay customer is created when a Cash App user approves a
        client's Cash App Pay request for the first time. This event allows
        clients to detect customers who are using a client's Cash App Pay
        integration for the first time.
      tags:
        - subpackage_customers
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `customer.created` for this
                    event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaData
                  description: Data about the Customer that was created.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this customer, typically used to
            associate the customer with a record in an external system. This
            value can be provided via the
            `CustomerRequest.customer_metadata.reference_id` attribute. Upon
            approval of the CustomerRequest, a corresponding customer resource
            is created with the `reference_id` attribute.
      required:
        - id
        - cashtag
    WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
      required:
        - customer
    WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the customer.
        object:
          $ref: >-
            #/components/schemas/WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the customer immediately after the customer was
            created.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `customer`.
      required:
        - id
        - object
        - type

```

---

# Event: customer.updated

POST 

**When is this event triggered?**

This event is created whenever a Cash App Pay customer is updated. The `customer.updated` event can be triggered when:
  - A customer updates their Cashtag.
  - A customer approves a request with a `customer_metadata.reference_id` attribute. Upon approval of the request, the customer's `reference_id` attribute is updated.

  > **Note:** If the `customer_metadata.reference_id` is the same as the customer's current `reference_id`, the customer will not be updated and the event will not be triggered.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/customer-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: customer.updated'
  version: subpackage_customers.customerUpdated
webhooks:
  customer-updated:
    post:
      operationId: customer-updated
      summary: 'Event: customer.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a Cash App Pay customer is updated. The
        `customer.updated` event can be triggered when:
          - A customer updates their Cashtag.
          - A customer approves a request with a `customer_metadata.reference_id` attribute. Upon approval of the request, the customer's `reference_id` attribute is updated.

          > **Note:** If the `customer_metadata.reference_id` is the same as the customer's current `reference_id`, the customer will not be updated and the event will not be triggered.
      tags:
        - subpackage_customers
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `customer.updated` for this
                    event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the Customer that was updated.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this customer, typically used to
            associate the customer with a record in an external system. This
            value can be provided via the
            `CustomerRequest.customer_metadata.reference_id` attribute. Upon
            approval of the CustomerRequest, a corresponding customer resource
            is created with the `reference_id` attribute.
      required:
        - id
        - cashtag
    WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
      required:
        - customer
    WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the customer.
        object:
          $ref: >-
            #/components/schemas/WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the customer immediately after the customer was
            updated.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `customer`.
      required:
        - id
        - object
        - type

```

---

# Event: customer.deleted

POST 

**When is this event triggered?**

This event is created whenever a Cash App Pay customer is deleted. The `customer.deleted` event will be triggered when a customer account is deleted by Cash App.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/customer-deleted

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: customer.deleted'
  version: subpackage_customers.customerDeleted
webhooks:
  customer-deleted:
    post:
      operationId: customer-deleted
      summary: 'Event: customer.deleted'
      description: >-
        **When is this event triggered?**


        This event is created whenever a Cash App Pay customer is deleted. The
        `customer.deleted` event will be triggered when a customer account is
        deleted by Cash App.
      tags:
        - subpackage_customers
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `customer.deleted` for this
                    event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaData
                  description: Data about the Customer that was deleted.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this customer, typically used to
            associate the customer with a record in an external system. This
            value can be provided via the
            `CustomerRequest.customer_metadata.reference_id` attribute. Upon
            approval of the CustomerRequest, a corresponding customer resource
            is created with the `reference_id` attribute.
      required:
        - id
        - cashtag
    WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
      required:
        - customer
    WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the customer.
        object:
          $ref: >-
            #/components/schemas/WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the customer immediately after the customer was
            deleted.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `customer`.
      required:
        - id
        - object
        - type

```

---

# List payments

GET https://api.cash.app/network/v1/payments

Returns a list of payments matching the given query parameters.

**This endpoint is rate limited to 100 QPS.**

Scopes: `PAYMENTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-payments

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List payments
  version: endpoint_payments.list-payments
paths:
  /payments:
    get:
      operationId: list-payments
      summary: List payments
      description: |-
        Returns a list of payments matching the given query parameters.

        **This endpoint is rate limited to 100 QPS.**

        Scopes: `PAYMENTS_READ`
      tags:
        - - subpackage_payments
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: reference_id
          in: query
          description: >-
            Filters results to only include payments with a `reference_id`
            matching the given value.
          required: false
          schema:
            type: string
        - name: customer_id
          in: query
          description: >-
            Filters results to only include payments made by a customer that
            matches the the given ID.
          required: false
          schema:
            type: string
        - name: merchant_id
          in: query
          description: >-
            Filters results to only include payments made to a merchant that
            matches the the given ID.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of payments to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments_list-payments_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    Payments_list-payments_Response_200:
      type: object
      properties:
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          description: List of payments matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - payments

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/payments")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/payments', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create payment

POST https://api.cash.app/network/v1/payments
Content-Type: application/json

Creates a payment from a customer to a merchant.


<Note>
  Creating a payment requires a grant that is associated with the `ON_FILE_PAYMENT` or `ONE_TIME_PAYMENT` actions. To generate a grant, use the Customer Request API.
</Note>

**This endpoint is not rate limited.**

Scopes: `PAYMENTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create payment
  version: endpoint_payments.create-payment
paths:
  /payments:
    post:
      operationId: create-payment
      summary: Create payment
      description: |-
        Creates a payment from a customer to a merchant.


        <Note>
          Creating a payment requires a grant that is associated with the `ON_FILE_PAYMENT` or `ONE_TIME_PAYMENT` actions. To generate a grant, use the Customer Request API.
        </Note>

        **This endpoint is not rate limited.**

        Scopes: `PAYMENTS_WRITE`
      tags:
        - - subpackage_payments
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments_create-payment_Response_201'
        '400':
          description: >-
            Bad Request


            If a `PAYMENT_DECLINE_*` error is returned, the payment will still
            be created, but with a `DECLINED` status. This payment will then
            appear in the response payload.


            <Note> 

            **`PAYMENT_DECLINE_*` errors consume one-time use grants.**
             This means you must repeat the Customer Request flow to get a new grant if you want to try taking the payment again. All other errors will not consume grants.
            </Note>
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                payment:
                  $ref: >-
                    #/components/schemas/PaymentsPostRequestBodyContentApplicationJsonSchemaPayment
                  description: Data about the payment to create.
              required:
                - idempotency_key
                - payment
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    PaymentsPostRequestBodyContentApplicationJsonSchemaPayment:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            The amount of money to charge the customer, in the lowest
            denomination of currency for the payment.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        merchant_id:
          type: string
          description: |-
            ID of the merchant to make the payment to.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: >-
            A grant ID from the Customer Request API that indicates permission
            to take the payment.


            Min length: `1`

            Max length: `256`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        capture:
          type: boolean
          default: true
          description: >-
            Whether or not to automatically capture the payment once it's
            created.


            Default: `true`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
      required:
        - amount
        - currency
        - merchant_id
        - grant_id
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    Payments_create-payment_Response_201:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "payment": {
        "amount": 100,
        "currency": "USD",
        "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
        "reference_id": "external-id",
        "capture": True,
        "enrichments": { "recurring_series_id": "string" }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","payment":{"amount":100,"currency":"USD","merchant_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","grant_id":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50","reference_id":"external-id","capture":true,"enrichments":{"recurring_series_id":"string"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/payments")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/payments', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "payment": {
    "amount": 100,
    "currency": "USD",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "reference_id": "external-id",
    "capture": true,
    "enrichments": {
      "recurring_series_id": "string"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "payment": [
    "amount": 100,
    "currency": "USD",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "reference_id": "external-id",
    "capture": true,
    "enrichments": ["recurring_series_id": "string"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/payments"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "payment": {
        "amount": 100,
        "currency": "USD",
        "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
        "reference_id": "external-id",
        "capture": True,
        "metadata": { "key": "value" },
        "enrichments": { "recurring_series_id": "string" }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","payment":{"amount":100,"currency":"USD","merchant_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","grant_id":"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50","reference_id":"external-id","capture":true,"metadata":{"key":"value"},"enrichments":{"recurring_series_id":"string"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/payments")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/payments', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "payment": {
    "amount": 100,
    "currency": "USD",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "reference_id": "external-id",
    "capture": true,
    "metadata": {
      "key": "value"
    },
    "enrichments": {
      "recurring_series_id": "string"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"payment\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"grant_id\": \"GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50\",\n    \"reference_id\": \"external-id\",\n    \"capture\": true,\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"enrichments\": {\n      \"recurring_series_id\": \"string\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "payment": [
    "amount": 100,
    "currency": "USD",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "reference_id": "external-id",
    "capture": true,
    "metadata": ["key": "value"],
    "enrichments": ["recurring_series_id": "string"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve payment

GET https://api.cash.app/network/v1/payments/{payment_id}

Retrieves a payment by its ID.

**This endpoint is not rate limited.**

Scopes: `PAYMENTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve payment
  version: endpoint_payments.retrieve-payment
paths:
  /payments/{payment_id}:
    get:
      operationId: retrieve-payment
      summary: Retrieve payment
      description: |-
        Retrieves a payment by its ID.

        **This endpoint is not rate limited.**

        Scopes: `PAYMENTS_READ`
      tags:
        - - subpackage_payments
      parameters:
        - name: payment_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments_retrieve-payment_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    Payments_retrieve-payment_Response_200:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
      required:
        - payment

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments/payment_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments/payment_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments/payment_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments/payment_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/payments/payment_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/payments/payment_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments/payment_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments/payment_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create incremental authorization

POST https://api.cash.app/network/v1/payments/{payment_id}/authorizations
Content-Type: application/json

Creates an authorization update for a payment. The authorization amount must be greater than or equal to the current authorized amount.

Use this endpoint for incremental authorization instead of overcapturing using the Capture payment endpoint. By creating additional payment authorizations exceeding the current authorized amount, you can request additional funds without risking the original amount being declined.

**This endpoint is not rate limited.** 

Scopes: `PAYMENTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-payment-authorization

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create incremental authorization
  version: endpoint_payments.create-payment-authorization
paths:
  /payments/{payment_id}/authorizations:
    post:
      operationId: create-payment-authorization
      summary: Create incremental authorization
      description: >-
        Creates an authorization update for a payment. The authorization amount
        must be greater than or equal to the current authorized amount.


        Use this endpoint for incremental authorization instead of overcapturing
        using the Capture payment endpoint. By creating additional payment
        authorizations exceeding the current authorized amount, you can request
        additional funds without risking the original amount being declined.


        **This endpoint is not rate limited.** 


        Scopes: `PAYMENTS_WRITE`
      tags:
        - - subpackage_payments
      parameters:
        - name: payment_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Payments_create-payment-authorization_Response_201
        '400':
          description: >-
            Bad Request


            If a AUTHORIZATION_DECLINE_* error is returned, the authorization
            will still be created, but with a DECLINED status. This
            authorization will then appear in the response payload.
          content: {}
        '404':
          description: Not Found
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                authorization:
                  $ref: >-
                    #/components/schemas/PaymentsPaymentIdAuthorizationsPostRequestBodyContentApplicationJsonSchemaAuthorization
                  description: Details about the authorization to create.
              required:
                - idempotency_key
                - authorization
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentsPaymentIdAuthorizationsPostRequestBodyContentApplicationJsonSchemaAuthorization:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            The updated total amount of money to collect from the customer, in
            the lowest denomination of currency for the payment.

            This value must be greater than or equal to the current authorized
            amount
        currency:
          $ref: '#/components/schemas/Currency'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - amount
        - currency
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payments_create-payment-authorization_Response_201:
      type: object
      properties:
        authorization:
          $ref: '#/components/schemas/Authorization'
      required:
        - authorization

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments/payment_id/authorizations"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "authorization": {
        "amount": 100,
        "currency": "USD"
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments/payment_id/authorizations';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","authorization":{"amount":100,"currency":"USD"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments/payment_id/authorizations"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"authorization\": {\n    \"amount\": 100,\n    \"currency\": \"USD\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments/payment_id/authorizations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"authorization\": {\n    \"amount\": 100,\n    \"currency\": \"USD\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/payments/payment_id/authorizations")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"authorization\": {\n    \"amount\": 100,\n    \"currency\": \"USD\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/payments/payment_id/authorizations', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "authorization": {
    "amount": 100,
    "currency": "USD"
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments/payment_id/authorizations");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"authorization\": {\n    \"amount\": 100,\n    \"currency\": \"USD\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "authorization": [
    "amount": 100,
    "currency": "USD"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments/payment_id/authorizations")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Capture payment

POST https://api.cash.app/network/v1/payments/{payment_id}/capture
Content-Type: application/json

Updates a payment with the given amount and finalizes it so that it can be paid out in the next nightly settlement batch.

**This endpoint is not rate limited.**

Scopes: `PAYMENTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/capture-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Capture payment
  version: endpoint_payments.capture-payment
paths:
  /payments/{payment_id}/capture:
    post:
      operationId: capture-payment
      summary: Capture payment
      description: >-
        Updates a payment with the given amount and finalizes it so that it can
        be paid out in the next nightly settlement batch.


        **This endpoint is not rate limited.**


        Scopes: `PAYMENTS_WRITE`
      tags:
        - - subpackage_payments
      parameters:
        - name: payment_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments_capture-payment_Response_200'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                amount:
                  type: integer
                  description: >-
                    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: `1`
              required:
                - idempotency_key
                - amount
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    Payments_capture-payment_Response_200:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
      required:
        - payment

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments/payment_id/capture"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "amount": 100
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments/payment_id/capture';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","amount":100}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments/payment_id/capture"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"amount\": 100\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments/payment_id/capture")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"amount\": 100\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/payments/payment_id/capture")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"amount\": 100\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/payments/payment_id/capture', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "amount": 100
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments/payment_id/capture");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"amount\": 100\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "amount": 100
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments/payment_id/capture")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Void payment

POST https://api.cash.app/network/v1/payments/{payment_id}/void

Moves an authorized payment to the voided state and releases the payment authorization from the customer's Cash App account.

<Note> 
You can only void an authorized payment. If a payment is captured, refund it instead. You cannot void any payment that has had an attempted capture. Authorizations not captured within seven days are automatically voided.
</Note>

This endpoint will return a success message if the payment was successfully voided _or_ if the payment was previously voided.

**This endpoint is not rate limited.**

Scopes: `PAYMENTS_WRITE`

Payment voids can be processed synchronously or asynchronously depending on payment type. The majority of voids are made synchronously.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/void-payment

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Void payment
  version: endpoint_payments.void-payment
paths:
  /payments/{payment_id}/void:
    post:
      operationId: void-payment
      summary: Void payment
      description: >-
        Moves an authorized payment to the voided state and releases the payment
        authorization from the customer's Cash App account.


        <Note> 

        You can only void an authorized payment. If a payment is captured,
        refund it instead. You cannot void any payment that has had an attempted
        capture. Authorizations not captured within seven days are automatically
        voided.

        </Note>


        This endpoint will return a success message if the payment was
        successfully voided _or_ if the payment was previously voided.


        **This endpoint is not rate limited.**


        Scopes: `PAYMENTS_WRITE`


        Payment voids can be processed synchronously or asynchronously depending
        on payment type. The majority of voids are made synchronously.
      tags:
        - - subpackage_payments
      parameters:
        - name: payment_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments_void-payment_Response_200'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    Payments_void-payment_Response_200:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
      required:
        - payment

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments/payment_id/void"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments/payment_id/void';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments/payment_id/void"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments/payment_id/void")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/payments/payment_id/void")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/payments/payment_id/void', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments/payment_id/void");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments/payment_id/void")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Void payment by idempotency key

POST https://api.cash.app/network/v1/payments/void-by-idempotency-key
Content-Type: application/json

Moves an authorized payment to the voided state and releases the payment authorization from the customer's Cash App account.

  <Note>
  You can only void an authorized payment. If a payment is captured, refund the payment instead.
  
   You cannot void any payment that has had an attempted capture. Authorizations not captured within seven days are automatically voided.
  </Note> 

This endpoint will return a success message if the payment was successfully voided _or_ if the payment was previously voided.

**This endpoint is not rate limited.**

Scopes: `PAYMENTS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/void-payment-by-idempotency-key

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Void payment by idempotency key
  version: endpoint_payments.void-payment-by-idempotency-key
paths:
  /payments/void-by-idempotency-key:
    post:
      operationId: void-payment-by-idempotency-key
      summary: Void payment by idempotency key
      description: >-
        Moves an authorized payment to the voided state and releases the payment
        authorization from the customer's Cash App account.

          <Note>
          You can only void an authorized payment. If a payment is captured, refund the payment instead.
          
           You cannot void any payment that has had an attempted capture. Authorizations not captured within seven days are automatically voided.
          </Note> 

        This endpoint will return a success message if the payment was
        successfully voided _or_ if the payment was previously voided.


        **This endpoint is not rate limited.**


        Scopes: `PAYMENTS_WRITE`
      tags:
        - - subpackage_payments
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Payments_void-payment-by-idempotency-key_Response_200
        '400':
          description: Bad Request
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  type: string
                  description: >-
                    Idempotency key used in the [create
                    payment](Network-API.v1.yaml/paths/~1payments/post) request
                    for the payment you want to void.
              required:
                - idempotency_key
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    Payments_void-payment-by-idempotency-key_Response_200:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
      required:
        - payment

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/payments/void-by-idempotency-key"

payload = { "idempotency_key": "string" }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/payments/void-by-idempotency-key';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/payments/void-by-idempotency-key"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/payments/void-by-idempotency-key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/payments/void-by-idempotency-key")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"string\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/payments/void-by-idempotency-key', [
  'body' => '{
  "idempotency_key": "string"
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/payments/void-by-idempotency-key");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["idempotency_key": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/payments/void-by-idempotency-key")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Payment

<EndpointSchemaSnippet endpoint="POST /payments" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
    "amount": 1500,
    "net_amount": 1000,
    "captured_amount": 1000,
    "voided_amount": 0,
    "refunded_amount": 100,
    "currency": "USD",
    "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "status": "AUTHORIZED",
    "created_at": "2022-01-01T12:00:00Z",
    "updated_at": "2022-01-05T12:00:00Z",
    "refund_ids": [
      "PWCR_da1v3j4p3z15y47adpzzq0whj"
    ],
    "reference_id": "external-id",
    "metadata": {},
    "enrichments": {
      "recurring_series_id": "string"
    },
    "decline_errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "MISSING_REQUIRED_FIELD",
        "detail": "Missing required parameter.",
        "field": "field_a[2].field_b"
      }
    ]
  }
  ```
</Aside>

---

# Enrichments

<EndpointSchemaSnippet endpoint="GET /enrichments-schema" selector="response.body" />

<Aside>
  ```json Example
  {
    "initiation": {
      "actor": "CUSTOMER"
    },
    "recurring_series_id": "string",
    "statement_descriptor": "string",
    "restricted_categories": [
      "ALCOHOL"
    ]
  }
  ```
</Aside>

---

# Event: payment.status.updated

POST 

**When is this event triggered?**

This event is created whenever a payment status is changed. The status change can be due to a couple different things:
  - An API client-initiated action to void or capture the payment
  - A payment auto-voiding after 7 days of not being captured

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/payment-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: payment.status.updated'
  version: subpackage_payments.paymentStatusUpdated
webhooks:
  payment-status-updated:
    post:
      operationId: payment-status-updated
      summary: 'Event: payment.status.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a payment status is changed. The status
        change can be due to a couple different things:
          - An API client-initiated action to void or capture the payment
          - A payment auto-voiding after 7 days of not being captured
      tags:
        - subpackage_payments
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `payment.status.updated`
                    for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the payment that had a status change.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
        - value: CANNABIS
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
      required:
        - payment
    WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the payment.
        object:
          $ref: >-
            #/components/schemas/WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the payment data immediately after the payment's
            status changed.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `payment`.
      required:
        - id
        - object
        - type

```

---

# List refunds

GET https://api.cash.app/network/v1/refunds

Returns a list of refunds matching the given query parameters.

**This endpoint is rate limited to 100 QPS.**

Scopes: `REFUNDS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-refunds

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List refunds
  version: endpoint_refunds.list-refunds
paths:
  /refunds:
    get:
      operationId: list-refunds
      summary: List refunds
      description: |-
        Returns a list of refunds matching the given query parameters.

        **This endpoint is rate limited to 100 QPS.**

        Scopes: `REFUNDS_READ`
      tags:
        - - subpackage_refunds
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: reference_id
          in: query
          description: >-
            Filters results to only include refunds with a `reference_id`
            matching the given value.
          required: false
          schema:
            type: string
        - name: customer_id
          in: query
          description: >-
            Filters results to only include refunds made to a customer that
            matches the the given ID.
          required: false
          schema:
            type: string
        - name: merchant_id
          in: query
          description: >-
            Filters results to only include refunds made by a merchant that
            matches the given ID.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of refunds to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refunds_list-refunds_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    Refunds_list-refunds_Response_200:
      type: object
      properties:
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
          description: List of refunds matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - refunds

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/refunds"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/refunds';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/refunds"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/refunds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/refunds")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/refunds', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/refunds");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create refund

POST https://api.cash.app/network/v1/refunds
Content-Type: application/json

Creates a refund from a merchant to a customer.

- To issue a refund, provide a `payment_id` in the request. 

The grant must be associated with the `ON_FILE_PAYMENT` actions.

To generate a grant to pass to this field, use the Customer Request API.

**This endpoint is not rate limited.**

Scopes: `REFUNDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-refund

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create refund
  version: endpoint_refunds.create-refund
paths:
  /refunds:
    post:
      operationId: create-refund
      summary: Create refund
      description: |-
        Creates a refund from a merchant to a customer.

        - To issue a refund, provide a `payment_id` in the request. 

        The grant must be associated with the `ON_FILE_PAYMENT` actions.

        To generate a grant to pass to this field, use the Customer Request API.

        **This endpoint is not rate limited.**

        Scopes: `REFUNDS_WRITE`
      tags:
        - - subpackage_refunds
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refunds_create-refund_Response_200'
        '400':
          description: >-
            Bad Request


            If a `REFUND_DECLINE_*` error is returned, the refund will still be
            created, but with a `DECLINED` status. This refund will then appear
            in the response payload.


            <Note> 

            **`REFUND_DECLINE_*` errors consume one-time use grants.**
             This means you must repeat the Customer Request flow to get a new grant if you want to try issuing
             the refund again. All other errors will not consume grants.
            </Note>
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                refund:
                  $ref: >-
                    #/components/schemas/RefundsPostRequestBodyContentApplicationJsonSchemaRefund
                  description: Details about the refund to create.
              required:
                - idempotency_key
                - refund
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    Metadata:
      type: object
      additionalProperties:
        type: string
    RefundsPostRequestBodyContentApplicationJsonSchemaRefund:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            The amount of money to refund the customer, in the lowest
            denomination of currency for the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        merchant_id:
          type: string
          description: |-
            ID of the merchant to make the refund from.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            For refunds, this is the ID of the payment to refund.

            Min length: `1`
            Max length: `128`
        capture:
          type: boolean
          default: true
          description: >-
            Whether or not to automatically capture the refund once it's
            created.


            Default: `true`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - amount
        - currency
        - merchant_id
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    Refunds_create-refund_Response_200:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
      required:
        - refund

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/refunds"

payload = {
    "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874",
    "refund": {
        "amount": 100,
        "currency": "USD",
        "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k",
        "capture": True,
        "reference_id": "external-id",
        "metadata": { "key": "value" }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/refunds';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"178f2318-a335-4be2-9792-6259a8887874","refund":{"amount":100,"currency":"USD","merchant_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","payment_id":"PWC_etdng09kyyqf5zr583v8xcs2k","capture":true,"reference_id":"external-id","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/refunds"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n  \"refund\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n    \"capture\": true,\n    \"reference_id\": \"external-id\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/refunds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n  \"refund\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n    \"capture\": true,\n    \"reference_id\": \"external-id\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/refunds")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n  \"refund\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n    \"capture\": true,\n    \"reference_id\": \"external-id\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/refunds', [
  'body' => '{
  "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874",
  "refund": {
    "amount": 100,
    "currency": "USD",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k",
    "capture": true,
    "reference_id": "external-id",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/refunds");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"178f2318-a335-4be2-9792-6259a8887874\",\n  \"refund\": {\n    \"amount\": 100,\n    \"currency\": \"USD\",\n    \"merchant_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n    \"payment_id\": \"PWC_etdng09kyyqf5zr583v8xcs2k\",\n    \"capture\": true,\n    \"reference_id\": \"external-id\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "178f2318-a335-4be2-9792-6259a8887874",
  "refund": [
    "amount": 100,
    "currency": "USD",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "payment_id": "PWC_etdng09kyyqf5zr583v8xcs2k",
    "capture": true,
    "reference_id": "external-id",
    "metadata": ["key": "value"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve refund

GET https://api.cash.app/network/v1/refunds/{refund_id}

Retrieves a refund by its ID.

**This endpoint is not rate limited.**

Scopes: `REFUNDS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-refund

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve refund
  version: endpoint_refunds.retrieve-refund
paths:
  /refunds/{refund_id}:
    get:
      operationId: retrieve-refund
      summary: Retrieve refund
      description: |-
        Retrieves a refund by its ID.

        **This endpoint is not rate limited.**

        Scopes: `REFUNDS_READ`
      tags:
        - - subpackage_refunds
      parameters:
        - name: refund_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refunds_retrieve-refund_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    Refunds_retrieve-refund_Response_200:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
      required:
        - refund

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/refunds/refund_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/refunds/refund_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/refunds/refund_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/refunds/refund_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/refunds/refund_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/refunds/refund_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/refunds/refund_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds/refund_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Capture refund

POST https://api.cash.app/network/v1/refunds/{refund_id}/capture
Content-Type: application/json

Finalizes a refund so that it can be allocated in the next nightly settlement batch.

**This endpoint is not rate limited.**

Scopes: `REFUNDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/capture-refund

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Capture refund
  version: endpoint_refunds.capture-refund
paths:
  /refunds/{refund_id}/capture:
    post:
      operationId: capture-refund
      summary: Capture refund
      description: >-
        Finalizes a refund so that it can be allocated in the next nightly
        settlement batch.


        **This endpoint is not rate limited.**


        Scopes: `REFUNDS_WRITE`
      tags:
        - - subpackage_refunds
      parameters:
        - name: refund_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refunds_capture-refund_Response_200'
        '404':
          description: Not Found
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
              required:
                - idempotency_key
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    Refunds_capture-refund_Response_200:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
      required:
        - refund

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/refunds/refund_id/capture"

payload = { "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19" }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/refunds/refund_id/capture';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/refunds/refund_id/capture"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/refunds/refund_id/capture")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/refunds/refund_id/capture")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/refunds/refund_id/capture', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/refunds/refund_id/capture");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds/refund_id/capture")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Void refund

POST https://api.cash.app/network/v1/refunds/{refund_id}/void

Moves an authorized refund to the voided state and removes the "pending refund" screen from a customer's Cash App account.

<Note> 
You can only void an authorized refund.
</Note>

**This endpoint is not rate limited.**

Scopes: `REFUNDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/void-refund

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Void refund
  version: endpoint_refunds.void-refund
paths:
  /refunds/{refund_id}/void:
    post:
      operationId: void-refund
      summary: Void refund
      description: >-
        Moves an authorized refund to the voided state and removes the "pending
        refund" screen from a customer's Cash App account.


        <Note> 

        You can only void an authorized refund.

        </Note>


        **This endpoint is not rate limited.**


        Scopes: `REFUNDS_WRITE`
      tags:
        - - subpackage_refunds
      parameters:
        - name: refund_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refunds_void-refund_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    Refunds_void-refund_Response_200:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
      required:
        - refund

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/refunds/refund_id/void"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/refunds/refund_id/void';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/refunds/refund_id/void"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/refunds/refund_id/void")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/refunds/refund_id/void")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/refunds/refund_id/void', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/refunds/refund_id/void");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds/refund_id/void")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Void refund by idempotency key

POST https://api.cash.app/network/v1/refunds/void-by-idempotency-key
Content-Type: application/json

Moves an authorized refund to the voided state using the idempotency key specified while creating the refund.

<Note> 
You can only void an authorized refund. If a refund is captured, there is no way to reverse it.
</Note>

In rare cases, an issue with an integration, network connectivity, or the Cash App Pay API may cause an API client to end up in a state where a refund is created in Cash App Pay, but the API client doesn't know the ID of the refund. This endpoint allows an API client to void a refund using _only_ the idempotency key to recover from these situations.

If you don't have the idempotency key or ID of the refund you want to void, you can use the [list refunds](Network-API.v1.yaml/paths/~1refunds/get) endpoint to try to search for the refund you're looking for.

**This endpoint is not rate limited.**

Scopes: `REFUNDS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/void-refund-by-idempotency-key

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Void refund by idempotency key
  version: endpoint_refunds.void-refund-by-idempotency-key
paths:
  /refunds/void-by-idempotency-key:
    post:
      operationId: void-refund-by-idempotency-key
      summary: Void refund by idempotency key
      description: >-
        Moves an authorized refund to the voided state using the idempotency key
        specified while creating the refund.


        <Note> 

        You can only void an authorized refund. If a refund is captured, there
        is no way to reverse it.

        </Note>


        In rare cases, an issue with an integration, network connectivity, or
        the Cash App Pay API may cause an API client to end up in a state where
        a refund is created in Cash App Pay, but the API client doesn't know the
        ID of the refund. This endpoint allows an API client to void a refund
        using _only_ the idempotency key to recover from these situations.


        If you don't have the idempotency key or ID of the refund you want to
        void, you can use the [list
        refunds](Network-API.v1.yaml/paths/~1refunds/get) endpoint to try to
        search for the refund you're looking for.


        **This endpoint is not rate limited.**


        Scopes: `REFUNDS_WRITE`
      tags:
        - - subpackage_refunds
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Refunds_void-refund-by-idempotency-key_Response_200
        '400':
          description: Bad Request
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
              required:
                - idempotency_key
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    Refunds_void-refund-by-idempotency-key_Response_200:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
      required:
        - refund

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/refunds/void-by-idempotency-key"

payload = { "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19" }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/refunds/void-by-idempotency-key';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/refunds/void-by-idempotency-key"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/refunds/void-by-idempotency-key")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/refunds/void-by-idempotency-key")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/refunds/void-by-idempotency-key', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/refunds/void-by-idempotency-key");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/refunds/void-by-idempotency-key")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Refund

<EndpointSchemaSnippet endpoint="POST /refunds" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "PWCR_da1v3j4p3z15y47adpzzq0whj",
    "amount": 2500,
    "currency": "USD",
    "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "status": "AUTHORIZED",
    "created_at": "2022-01-01T12:00:00Z",
    "updated_at": "2022-01-05T12:00:00Z",
    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "payment_id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
    "reference_id": "external-id",
    "metadata": {},
    "decline_errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "MISSING_REQUIRED_FIELD",
        "detail": "Missing required parameter.",
        "field": "field_a[2].field_b"
      }
    ]
  }
  ```
</Aside>

---

# Event: refund.status.updated

POST 

**When is this event triggered?**

This event is created whenever a refund status is changed. The status change can be due to a couple different things:
  - An API client-initiated action to void or capture the refund
  - A refund auto-voiding after 7 days of not being captured

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/refund-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: refund.status.updated'
  version: subpackage_refunds.refundStatusUpdated
webhooks:
  refund-status-updated:
    post:
      operationId: refund-status-updated
      summary: 'Event: refund.status.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a refund status is changed. The status
        change can be due to a couple different things:
          - An API client-initiated action to void or capture the refund
          - A refund auto-voiding after 7 days of not being captured
      tags:
        - subpackage_refunds
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `refund.status.updated` for
                    this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the refund that had a status change.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Metadata:
      type: object
      additionalProperties:
        type: string
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
      required:
        - refund
    WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the refund.
        object:
          $ref: >-
            #/components/schemas/WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the refund immediately after the refund's status
            changed.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `refund`.
      required:
        - id
        - object
        - type

```

---

# List disputes

GET https://api.cash.app/network/v1/disputes

Returns a list of all disputes (matching the given query parameters) associated with payments created by this client.

**This endpoint is rate limited to 50 QPS.**

Scopes: `DISPUTES_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-disputes

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List disputes
  version: endpoint_disputes.list-disputes
paths:
  /disputes:
    get:
      operationId: list-disputes
      summary: List disputes
      description: >-
        Returns a list of all disputes (matching the given query parameters)
        associated with payments created by this client.


        **This endpoint is rate limited to 50 QPS.**


        Scopes: `DISPUTES_READ`
      tags:
        - - subpackage_disputes
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of disputes to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: merchant_id
          in: query
          description: >-
            Filters results to only include disputes filed against a merchant
            that matches the the given ID.
          required: false
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disputes_list-disputes_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    Disputes_list-disputes_Response_200:
      type: object
      properties:
        disputes:
          type: array
          items:
            $ref: '#/components/schemas/Dispute'
          description: List of disputes matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - disputes

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/disputes")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/disputes', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve dispute

GET https://api.cash.app/network/v1/disputes/{dispute_id}

Retrieves a dispute by its ID.

**This endpoint is not rate limited.**

Scopes: `DISPUTES_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve dispute
  version: endpoint_disputes.retrieve-dispute
paths:
  /disputes/{dispute_id}:
    get:
      operationId: retrieve-dispute
      summary: Retrieve dispute
      description: |-
        Retrieves a dispute by its ID.

        **This endpoint is not rate limited.**

        Scopes: `DISPUTES_READ`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disputes_retrieve-dispute_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    Disputes_retrieve-dispute_Response_200:
      type: object
      properties:
        dispute:
          $ref: '#/components/schemas/Dispute'
      required:
        - dispute

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/disputes/dispute_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/disputes/dispute_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Accept dispute

POST https://api.cash.app/network/v1/disputes/{dispute_id}/accept

Resolves a dispute by having the merchant accept responsibility for it. This leads to a "loss" of the dispute from the merchant's perspective, and a "win" of the dispute from the customer's perspective.

<Note> 
After a dispute is accepted, the decision is final; it can never be changed.
</Note>

**This endpoint is not rate limited.**

Scopes: `DISPUTES_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/accept-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Accept dispute
  version: endpoint_disputes.accept-dispute
paths:
  /disputes/{dispute_id}/accept:
    post:
      operationId: accept-dispute
      summary: Accept dispute
      description: >-
        Resolves a dispute by having the merchant accept responsibility for it.
        This leads to a "loss" of the dispute from the merchant's perspective,
        and a "win" of the dispute from the customer's perspective.


        <Note> 

        After a dispute is accepted, the decision is final; it can never be
        changed.

        </Note>


        **This endpoint is not rate limited.**


        Scopes: `DISPUTES_WRITE`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disputes_accept-dispute_Response_200'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    Disputes_accept-dispute_Response_200:
      type: object
      properties:
        dispute:
          $ref: '#/components/schemas/Dispute'

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/accept"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/accept';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/accept"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/accept")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/disputes/dispute_id/accept")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/disputes/dispute_id/accept', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/accept");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/accept")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Challenge dispute

POST https://api.cash.app/network/v1/disputes/{dispute_id}/challenge

Submits evidence uploaded to this dispute to Cash App Pay for review.

After Cash App Pay reviews the dispute, a final decision will be reached and funds will be settled appropriately. If this endpoint is not called by the `response_due_at` timestamp, the merchant will automatically "lose" the dispute.

<Info> 
Challenging a dispute does not guarantee that the merchant will "win" it. It only means that it will be reviewed, instead of being automatically accepted by the merchant.
</Info>

**This endpoint is not rate limited.**

Scopes: `DISPUTES_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/challenge-dispute

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Challenge dispute
  version: endpoint_disputes.challenge-dispute
paths:
  /disputes/{dispute_id}/challenge:
    post:
      operationId: challenge-dispute
      summary: Challenge dispute
      description: >-
        Submits evidence uploaded to this dispute to Cash App Pay for review.


        After Cash App Pay reviews the dispute, a final decision will be reached
        and funds will be settled appropriately. If this endpoint is not called
        by the `response_due_at` timestamp, the merchant will automatically
        "lose" the dispute.


        <Info> 

        Challenging a dispute does not guarantee that the merchant will "win"
        it. It only means that it will be reviewed, instead of being
        automatically accepted by the merchant.

        </Info>


        **This endpoint is not rate limited.**


        Scopes: `DISPUTES_WRITE`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disputes_challenge-dispute_Response_200'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    Disputes_challenge-dispute_Response_200:
      type: object
      properties:
        dispute:
          $ref: '#/components/schemas/Dispute'
      required:
        - dispute

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/challenge"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/challenge';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/challenge"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/challenge")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/disputes/dispute_id/challenge")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/disputes/dispute_id/challenge', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/challenge");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/challenge")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# List dispute evidence

GET https://api.cash.app/network/v1/disputes/{dispute_id}/evidence

Returns a list of all pieces of evidence associated with the given dispute.

**This endpoint is rate limited to 50 QPS.**

Scopes: `DISPUTES_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-dispute-evidence

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List dispute evidence
  version: endpoint_disputes.list-dispute-evidence
paths:
  /disputes/{dispute_id}/evidence:
    get:
      operationId: list-dispute-evidence
      summary: List dispute evidence
      description: >-
        Returns a list of all pieces of evidence associated with the given
        dispute.


        **This endpoint is rate limited to 50 QPS.**


        Scopes: `DISPUTES_READ`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of pieces of dispute evidence to return
          required: false
          schema:
            type: integer
            default: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Disputes_list-dispute-evidence_Response_200
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    DisputeEvidenceCategory:
      type: string
      enum:
        - value: GENERIC_EVIDENCE
        - value: ONLINE_OR_APP_ACCESS_LOG
        - value: AUTHORIZATION_DOCUMENTATION
        - value: CANCELLATION_OR_REFUND_DOCUMENTATION
        - value: CARDHOLDER_COMMUNICATION
        - value: CARDHOLDER_INFORMATION
        - value: PURCHASE_ACKNOWLEDGEMENT
        - value: DUPLICATE_CHARGE_DOCUMENTATION
        - value: PRODUCT_OR_SERVICE_DESCRIPTION
        - value: RECEIPT
        - value: SERVICE_RECEIVED_DOCUMENTATION
        - value: PROOF_OF_DELIVERY_DOCUMENTATION
        - value: RELATED_TRANSACTION_DOCUMENTATION
        - value: REBUTTAL_EXPLANATION
        - value: TRACKING_NUMBER
    DisputeEvidenceFileContentType:
      type: string
      enum:
        - value: application/pdf
        - value: image/heic
        - value: image/heif
        - value: image/jpeg
        - value: image/png
        - value: image/tiff
    DisputeEvidenceFile:
      type: object
      properties:
        filename:
          type: string
          description: >-
            Name of the uploaded file. It should be descriptive enough to
            indicate what type of information is contained in the uploaded file.
        content_type:
          $ref: '#/components/schemas/DisputeEvidenceFileContentType'
          description: |-
            The MIME type of the uploaded file.

            Current values:

            - `application/pdf`
            - `image/heic`
            - `image/heif`
            - `image/jpeg`
            - `image/png`
            - `image/tiff`
      required:
        - filename
        - content_type
    DisputeEvidenceType:
      type: string
      enum:
        - value: FILE
        - value: TEXT
    Metadata:
      type: object
      additionalProperties:
        type: string
    DisputeEvidence:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute evidence issued by Cash App.

            Min length: `1`
            Max length: `128`
        dispute_id:
          type: string
          description: |-
            ID of the dispute this evidence is associated with.

            Min length: `1`
            Max length: `128`
        category:
          $ref: '#/components/schemas/DisputeEvidenceCategory'
          description: >-
            Describes what type of information is contained in this piece of
            evidence.


            Current values:


            - `GENERIC_EVIDENCE`: Default evidence type used if no other
            category applies.

            - `ONLINE_OR_APP_ACCESS_LOG`: Server or activity logs that show
            proof of the cardholder’s identity and that the cardholder
            successfully ordered and received the goods (digitally or
            otherwise). Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholder’s name and email address linked to a
            cardholder profile held by the seller, proof the same device and
            card (used in dispute) were previously used in prior undisputed
            transaction, and any related detailed activity.

            - `AUTHORIZATION_DOCUMENTATION`: **[File Only]** Evidence that the
            cardholder did provide authorization for the charge. Example
            evidence includes a signed credit card authorization.

            - `CANCELLATION_OR_REFUND_DOCUMENTATION`: Evidence that the
            cardholder acknowledged your refund or cancellation policy. Example
            evidence includes a signature or checkbox showing the cardholder’s
            acknowledgement of your refund or cancellation policy.

            - `CARDHOLDER_COMMUNICATION`: **[File Only]** Evidence that shows
            relevant communication with the cardholder. Example evidence
            includes emails or texts that show the cardholder received
            goods/services or demonstrate cardholder satisfaction.

            - `CARDHOLDER_INFORMATION`: Evidence that validates the customer's
            identity. Example evidence includes personally identifiable details
            such as name, email address, purchaser IP address, and a copy of the
            cardholder ID.

            - `PURCHASE_ACKNOWLEDGEMENT`: Evidence that shows proof of the
            sale/transaction. Example evidence includes an invoice, contract, or
            other item showing the customer’s acknowledgement of the purchase
            and your terms.

            - `DUPLICATE_CHARGE_DOCUMENTATION`: **[File Only]** Evidence that
            shows the charges in question are valid and distinct from one
            another. Example evidence includes receipts, shipping labels, and
            invoices along with their distinct payment IDs.

            - `PRODUCT_OR_SERVICE_DESCRIPTION`: A description of the product or
            service sold.

            - `RECEIPT`: A receipt or message sent to the cardholder detailing
            the charge. Note: You do not need to upload the Square receipt;
            Square submits the receipt on your behalf.

            - `SERVICE_RECEIVED_DOCUMENTATION`: Evidence that the service was
            provided to the cardholder or the expected date that services will
            be rendered. Example evidence includes a signed delivery form, work
            order, expected delivery date, or other written agreements.

            - `PROOF_OF_DELIVERY_DOCUMENTATION`: Evidence that shows the product
            was provided to the cardholder or the expected date of delivery.
            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.

            - `RELATED_TRANSACTION_DOCUMENTATION`: Evidence that shows the
            cardholder previously processed transactions on the same card and
            did not dispute them.

            - `REBUTTAL_EXPLANATION`: An explanation of why the cardholder’s
            claim is invalid. Example evidence includes an explanation of why
            each distinct charge is a legitimate purchase, why the cardholder’s
            claim for credit owed due to their attempt to cancel, return, or
            refund is invalid per your stated policy and cardholder agreement,
            or an explanation of how the cardholder did not attempt to remedy
            the issue with you first to receive credit.

            - `TRACKING_NUMBER`: The tracking number for the order provided by
            the shipping carrier. If you have multiple numbers, they need to be
            submitted individually as separate pieces of evidence.
        file:
          $ref: '#/components/schemas/DisputeEvidenceFile'
          description: >-
            If the evidence is of type `FILE`, contains metadata about the
            binary file uploaded as evidence.
        text:
          type: string
          description: >-
            If the evidence is of type `TEXT`, contains the blob of text created
            as evidence.


            Min length: `1`

            Max length: `500`
        type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: |-
            Indicates if the evidence is a file or plain text.

            Current values:
            - `TEXT`: The evidence is a blob of text under 500 characters.
            - `FILE`: The evidence is an uploaded binary file.
        created_at:
          type: string
          format: date-time
          description: >-
            When this evidence was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - dispute_id
        - category
        - type
        - created_at
    Disputes_list-dispute-evidence_Response_200:
      type: object
      properties:
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/DisputeEvidence'
          description: >-
            List of pieces of evidence for the dispute matching the given query
            parameters
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - evidence

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/disputes/dispute_id/evidence")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create dispute evidence text

POST https://api.cash.app/network/v1/disputes/{dispute_id}/evidence-text
Content-Type: application/json

Creates a piece of evidence for the given dispute from a blob of plain text, which can then be submitted with the [challenge dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge) endpoint.

If you have more than 500 characters of text to submit as evidence, split it into multiple pieces where possible.

<Note> 
Uploading evidence does not challenge the dispute. Make sure to call the [challenge dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge) endpoint before the `response_due_at` timestamp, or else the merchant will automatically "lose" the dispute.
</Note>

**This endpoint is not rate limited.**

Scopes: `DISPUTES_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-text

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create dispute evidence text
  version: endpoint_disputes.create-dispute-evidence-text
paths:
  /disputes/{dispute_id}/evidence-text:
    post:
      operationId: create-dispute-evidence-text
      summary: Create dispute evidence text
      description: >-
        Creates a piece of evidence for the given dispute from a blob of plain
        text, which can then be submitted with the [challenge
        dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge)
        endpoint.


        If you have more than 500 characters of text to submit as evidence,
        split it into multiple pieces where possible.


        <Note> 

        Uploading evidence does not challenge the dispute. Make sure to call the
        [challenge
        dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge)
        endpoint before the `response_due_at` timestamp, or else the merchant
        will automatically "lose" the dispute.

        </Note>


        **This endpoint is not rate limited.**


        Scopes: `DISPUTES_WRITE`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Disputes_create-dispute-evidence-text_Response_201
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                evidence:
                  $ref: >-
                    #/components/schemas/DisputesDisputeIdEvidenceTextPostRequestBodyContentApplicationJsonSchemaEvidence
                  description: Details about the evidence to create.
              required:
                - idempotency_key
                - evidence
components:
  schemas:
    IdempotencyKey:
      type: string
    DisputesDisputeIdEvidenceTextPostRequestBodyContentApplicationJsonSchemaEvidenceCategory:
      type: string
      enum:
        - value: GENERIC_EVIDENCE
        - value: ONLINE_OR_APP_ACCESS_LOG
        - value: AUTHORIZATION_DOCUMENTATION
        - value: CANCELLATION_OR_REFUND_DOCUMENTATION
        - value: CARDHOLDER_COMMUNICATION
        - value: CARDHOLDER_INFORMATION
        - value: PURCHASE_ACKNOWLEDGEMENT
        - value: DUPLICATE_CHARGE_DOCUMENTATION
        - value: PRODUCT_OR_SERVICE_DESCRIPTION
        - value: RECEIPT
        - value: SERVICE_RECEIVED_DOCUMENTATION
        - value: PROOF_OF_DELIVERY_DOCUMENTATION
        - value: RELATED_TRANSACTION_DOCUMENTATION
        - value: REBUTTAL_EXPLANATION
        - value: TRACKING_NUMBER
    Metadata:
      type: object
      additionalProperties:
        type: string
    DisputesDisputeIdEvidenceTextPostRequestBodyContentApplicationJsonSchemaEvidence:
      type: object
      properties:
        category:
          $ref: >-
            #/components/schemas/DisputesDisputeIdEvidenceTextPostRequestBodyContentApplicationJsonSchemaEvidenceCategory
          description: >-
            Describes what type of information is contained in this piece of
            evidence.


            Current values:


            - `GENERIC_EVIDENCE`: Default evidence type used if no other
            category applies.

            - `ONLINE_OR_APP_ACCESS_LOG`: Server or activity logs that show
            proof of the cardholder’s identity and that the cardholder
            successfully ordered and received the goods (digitally or
            otherwise). Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholder’s name and email address linked to a
            cardholder profile held by the seller, proof the same device and
            card (used in dispute) were previously used in prior undisputed
            transaction, and any related detailed activity.

            - `AUTHORIZATION_DOCUMENTATION`: **[File Only]** Evidence that the
            cardholder did provide authorization for the charge. Example
            evidence includes a signed credit card authorization.

            - `CANCELLATION_OR_REFUND_DOCUMENTATION`: Evidence that the
            cardholder acknowledged your refund or cancellation policy. Example
            evidence includes a signature or checkbox showing the cardholder’s
            acknowledgement of your refund or cancellation policy.

            - `CARDHOLDER_COMMUNICATION`: **[File Only]** Evidence that shows
            relevant communication with the cardholder. Example evidence
            includes emails or texts that show the cardholder received
            goods/services or demonstrate cardholder satisfaction.

            - `CARDHOLDER_INFORMATION`: Evidence that validates the customer's
            identity. Example evidence includes personally identifiable details
            such as name, email address, purchaser IP address, and a copy of the
            cardholder ID.

            - `PURCHASE_ACKNOWLEDGEMENT`: Evidence that shows proof of the
            sale/transaction. Example evidence includes an invoice, contract, or
            other item showing the customer’s acknowledgement of the purchase
            and your terms.

            - `DUPLICATE_CHARGE_DOCUMENTATION`: **[File Only]** Evidence that
            shows the charges in question are valid and distinct from one
            another. Example evidence includes receipts, shipping labels, and
            invoices along with their distinct payment IDs.

            - `PRODUCT_OR_SERVICE_DESCRIPTION`: A description of the product or
            service sold.

            - `RECEIPT`: A receipt or message sent to the cardholder detailing
            the charge. Note: You do not need to upload the Square receipt;
            Square submits the receipt on your behalf.

            - `SERVICE_RECEIVED_DOCUMENTATION`: Evidence that the service was
            provided to the cardholder or the expected date that services will
            be rendered. Example evidence includes a signed delivery form, work
            order, expected delivery date, or other written agreements.

            - `PROOF_OF_DELIVERY_DOCUMENTATION`: Evidence that shows the product
            was provided to the cardholder or the expected date of delivery.
            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.

            - `RELATED_TRANSACTION_DOCUMENTATION`: Evidence that shows the
            cardholder previously processed transactions on the same card and
            did not dispute them.

            - `REBUTTAL_EXPLANATION`: An explanation of why the cardholder’s
            claim is invalid. Example evidence includes an explanation of why
            each distinct charge is a legitimate purchase, why the cardholder’s
            claim for credit owed due to their attempt to cancel, return, or
            refund is invalid per your stated policy and cardholder agreement,
            or an explanation of how the cardholder did not attempt to remedy
            the issue with you first to receive credit.

            - `TRACKING_NUMBER`: The tracking number for the order provided by
            the shipping carrier. If you have multiple numbers, they need to be
            submitted individually as separate pieces of evidence.
        text:
          type: string
          description: The blob of text to upload as evidence.
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - category
        - text
    DisputeEvidenceCategory:
      type: string
      enum:
        - value: GENERIC_EVIDENCE
        - value: ONLINE_OR_APP_ACCESS_LOG
        - value: AUTHORIZATION_DOCUMENTATION
        - value: CANCELLATION_OR_REFUND_DOCUMENTATION
        - value: CARDHOLDER_COMMUNICATION
        - value: CARDHOLDER_INFORMATION
        - value: PURCHASE_ACKNOWLEDGEMENT
        - value: DUPLICATE_CHARGE_DOCUMENTATION
        - value: PRODUCT_OR_SERVICE_DESCRIPTION
        - value: RECEIPT
        - value: SERVICE_RECEIVED_DOCUMENTATION
        - value: PROOF_OF_DELIVERY_DOCUMENTATION
        - value: RELATED_TRANSACTION_DOCUMENTATION
        - value: REBUTTAL_EXPLANATION
        - value: TRACKING_NUMBER
    DisputeEvidenceFileContentType:
      type: string
      enum:
        - value: application/pdf
        - value: image/heic
        - value: image/heif
        - value: image/jpeg
        - value: image/png
        - value: image/tiff
    DisputeEvidenceFile:
      type: object
      properties:
        filename:
          type: string
          description: >-
            Name of the uploaded file. It should be descriptive enough to
            indicate what type of information is contained in the uploaded file.
        content_type:
          $ref: '#/components/schemas/DisputeEvidenceFileContentType'
          description: |-
            The MIME type of the uploaded file.

            Current values:

            - `application/pdf`
            - `image/heic`
            - `image/heif`
            - `image/jpeg`
            - `image/png`
            - `image/tiff`
      required:
        - filename
        - content_type
    DisputeEvidenceType:
      type: string
      enum:
        - value: FILE
        - value: TEXT
    DisputeEvidence:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute evidence issued by Cash App.

            Min length: `1`
            Max length: `128`
        dispute_id:
          type: string
          description: |-
            ID of the dispute this evidence is associated with.

            Min length: `1`
            Max length: `128`
        category:
          $ref: '#/components/schemas/DisputeEvidenceCategory'
          description: >-
            Describes what type of information is contained in this piece of
            evidence.


            Current values:


            - `GENERIC_EVIDENCE`: Default evidence type used if no other
            category applies.

            - `ONLINE_OR_APP_ACCESS_LOG`: Server or activity logs that show
            proof of the cardholder’s identity and that the cardholder
            successfully ordered and received the goods (digitally or
            otherwise). Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholder’s name and email address linked to a
            cardholder profile held by the seller, proof the same device and
            card (used in dispute) were previously used in prior undisputed
            transaction, and any related detailed activity.

            - `AUTHORIZATION_DOCUMENTATION`: **[File Only]** Evidence that the
            cardholder did provide authorization for the charge. Example
            evidence includes a signed credit card authorization.

            - `CANCELLATION_OR_REFUND_DOCUMENTATION`: Evidence that the
            cardholder acknowledged your refund or cancellation policy. Example
            evidence includes a signature or checkbox showing the cardholder’s
            acknowledgement of your refund or cancellation policy.

            - `CARDHOLDER_COMMUNICATION`: **[File Only]** Evidence that shows
            relevant communication with the cardholder. Example evidence
            includes emails or texts that show the cardholder received
            goods/services or demonstrate cardholder satisfaction.

            - `CARDHOLDER_INFORMATION`: Evidence that validates the customer's
            identity. Example evidence includes personally identifiable details
            such as name, email address, purchaser IP address, and a copy of the
            cardholder ID.

            - `PURCHASE_ACKNOWLEDGEMENT`: Evidence that shows proof of the
            sale/transaction. Example evidence includes an invoice, contract, or
            other item showing the customer’s acknowledgement of the purchase
            and your terms.

            - `DUPLICATE_CHARGE_DOCUMENTATION`: **[File Only]** Evidence that
            shows the charges in question are valid and distinct from one
            another. Example evidence includes receipts, shipping labels, and
            invoices along with their distinct payment IDs.

            - `PRODUCT_OR_SERVICE_DESCRIPTION`: A description of the product or
            service sold.

            - `RECEIPT`: A receipt or message sent to the cardholder detailing
            the charge. Note: You do not need to upload the Square receipt;
            Square submits the receipt on your behalf.

            - `SERVICE_RECEIVED_DOCUMENTATION`: Evidence that the service was
            provided to the cardholder or the expected date that services will
            be rendered. Example evidence includes a signed delivery form, work
            order, expected delivery date, or other written agreements.

            - `PROOF_OF_DELIVERY_DOCUMENTATION`: Evidence that shows the product
            was provided to the cardholder or the expected date of delivery.
            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.

            - `RELATED_TRANSACTION_DOCUMENTATION`: Evidence that shows the
            cardholder previously processed transactions on the same card and
            did not dispute them.

            - `REBUTTAL_EXPLANATION`: An explanation of why the cardholder’s
            claim is invalid. Example evidence includes an explanation of why
            each distinct charge is a legitimate purchase, why the cardholder’s
            claim for credit owed due to their attempt to cancel, return, or
            refund is invalid per your stated policy and cardholder agreement,
            or an explanation of how the cardholder did not attempt to remedy
            the issue with you first to receive credit.

            - `TRACKING_NUMBER`: The tracking number for the order provided by
            the shipping carrier. If you have multiple numbers, they need to be
            submitted individually as separate pieces of evidence.
        file:
          $ref: '#/components/schemas/DisputeEvidenceFile'
          description: >-
            If the evidence is of type `FILE`, contains metadata about the
            binary file uploaded as evidence.
        text:
          type: string
          description: >-
            If the evidence is of type `TEXT`, contains the blob of text created
            as evidence.


            Min length: `1`

            Max length: `500`
        type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: |-
            Indicates if the evidence is a file or plain text.

            Current values:
            - `TEXT`: The evidence is a blob of text under 500 characters.
            - `FILE`: The evidence is an uploaded binary file.
        created_at:
          type: string
          format: date-time
          description: >-
            When this evidence was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - dispute_id
        - category
        - type
        - created_at
    Disputes_create-dispute-evidence-text_Response_201:
      type: object
      properties:
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence-text"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "evidence": {
        "category": "GENERIC_EVIDENCE",
        "text": "evidence as text"
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-text';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","evidence":{"category":"GENERIC_EVIDENCE","text":"evidence as text"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence-text"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence-text")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/disputes/dispute_id/evidence-text")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-text', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": {
    "category": "GENERIC_EVIDENCE",
    "text": "evidence as text"
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence-text");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": [
    "category": "GENERIC_EVIDENCE",
    "text": "evidence as text"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence-text")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence-text"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "evidence": {
        "category": "GENERIC_EVIDENCE",
        "text": "evidence as text",
        "metadata": { "key": "value" }
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-text';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","evidence":{"category":"GENERIC_EVIDENCE","text":"evidence as text","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence-text"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence-text")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/disputes/dispute_id/evidence-text")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-text', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": {
    "category": "GENERIC_EVIDENCE",
    "text": "evidence as text",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence-text");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"text\": \"evidence as text\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": [
    "category": "GENERIC_EVIDENCE",
    "text": "evidence as text",
    "metadata": ["key": "value"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence-text")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create dispute evidence file

POST https://api.cash.app/network/v1/disputes/{dispute_id}/evidence-file
Content-Type: multipart/form-data

Uploads a binary file as a piece of evidence for the given dispute, which can then be submitted with the [challenge dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge) endpoint.

The file must be one of the supported formats, or else it may not be usable to challenge the dispute:

- `JPEG`
- `HEIC`
- `HEIF`
- `PNG`
- `PDF`
- `TIFF`

<Note> 
Uploading evidence does not challenge the dispute. Make sure to call the [challenge dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge) endpoint before the `response_due_at` timestamp, or else the merchant will automatically "lose" the dispute.
</Note>

**This endpoint is not rate limited.**

Scopes: `DISPUTES_WRITE`

---

### Example request payload (cURL)

The following example shows how to make a request to upload a dispute file. There are two "parts" of the request:

- `request`, a JSON blob that contains details about the file to upload
- `file`, which contains the binary data for the file to be uploaded.

Using `cURL` to make the request, the request would look like the example below. Please refer to documentation for your particular language / framework and `multipart/form-data` requests to see how you should implement it in your own codebase.

Please refer to [Signing Multipart Requests](https://developers.cash.app/docs/partner/technical-documentation/api-fundamentals/requests/signing-requests) to compute a signature for the request.

```curl
curl --request POST 'https://sandbox.api.cash.app/network/v1/disputes/DSPT_ztqn5hd8wmrzjzavmf60pjbzf/evidence-file' \
--header 'Accept: application/json' \
--header 'Authorization: Client CLIENT_ID API_KEY_ID' \
--header 'Content-Type: multipart/form-data' \
--header 'X-Region: PDX' \
--form 'request={
  "idempotency_key": "e445c3fb-2caa-46fd-b0d3-aa7c7b00ab41",
  "evidence": {
    "category": "AUTHORIZATION_DOCUMENTATION",
    "file": {
      "filename": "evidence.pdf",
      "content_type": "application/pdf"
    }
  }
}' \
--form 'signature=SIGNATURE' \
--form 'file=path-to-file.pdf' 
```

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/create-dispute-evidence-file

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create dispute evidence file
  version: endpoint_disputes.create-dispute-evidence-file
paths:
  /disputes/{dispute_id}/evidence-file:
    post:
      operationId: create-dispute-evidence-file
      summary: Create dispute evidence file
      description: >-
        Uploads a binary file as a piece of evidence for the given dispute,
        which can then be submitted with the [challenge
        dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge)
        endpoint.


        The file must be one of the supported formats, or else it may not be
        usable to challenge the dispute:


        - `JPEG`

        - `HEIC`

        - `HEIF`

        - `PNG`

        - `PDF`

        - `TIFF`


        <Note> 

        Uploading evidence does not challenge the dispute. Make sure to call the
        [challenge
        dispute](Network-API.v1.yaml/paths/~1disputes~1{dispute_id}~1challenge)
        endpoint before the `response_due_at` timestamp, or else the merchant
        will automatically "lose" the dispute.

        </Note>


        **This endpoint is not rate limited.**


        Scopes: `DISPUTES_WRITE`


        ---


        ### Example request payload (cURL)


        The following example shows how to make a request to upload a dispute
        file. There are two "parts" of the request:


        - `request`, a JSON blob that contains details about the file to upload

        - `file`, which contains the binary data for the file to be uploaded.


        Using `cURL` to make the request, the request would look like the
        example below. Please refer to documentation for your particular
        language / framework and `multipart/form-data` requests to see how you
        should implement it in your own codebase.


        Please refer to [Signing Multipart
        Requests](https://developers.cash.app/docs/partner/technical-documentation/api-fundamentals/requests/signing-requests)
        to compute a signature for the request.


        ```curl

        curl --request POST
        'https://sandbox.api.cash.app/network/v1/disputes/DSPT_ztqn5hd8wmrzjzavmf60pjbzf/evidence-file'
        \

        --header 'Accept: application/json' \

        --header 'Authorization: Client CLIENT_ID API_KEY_ID' \

        --header 'Content-Type: multipart/form-data' \

        --header 'X-Region: PDX' \

        --form 'request={
          "idempotency_key": "e445c3fb-2caa-46fd-b0d3-aa7c7b00ab41",
          "evidence": {
            "category": "AUTHORIZATION_DOCUMENTATION",
            "file": {
              "filename": "evidence.pdf",
              "content_type": "application/pdf"
            }
          }
        }' \

        --form 'signature=SIGNATURE' \

        --form 'file=path-to-file.pdf' 

        ```
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Disputes_create-dispute-evidence-file_Response_201
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
      requestBody:
        description: ''
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                request:
                  $ref: >-
                    #/components/schemas/DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequest
                  description: >-
                    JSON-encoded payload describing the contents of the file
                    uploaded
                file:
                  type: string
                  format: binary
                  description: |-
                    Binary file to upload

                    Min size: `1 byte`
                    Max size: `5 megabytes`
              required:
                - request
                - file
components:
  schemas:
    IdempotencyKey:
      type: string
    DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceCategory:
      type: string
      enum:
        - value: GENERIC_EVIDENCE
        - value: ONLINE_OR_APP_ACCESS_LOG
        - value: AUTHORIZATION_DOCUMENTATION
        - value: CANCELLATION_OR_REFUND_DOCUMENTATION
        - value: CARDHOLDER_COMMUNICATION
        - value: CARDHOLDER_INFORMATION
        - value: PURCHASE_ACKNOWLEDGEMENT
        - value: DUPLICATE_CHARGE_DOCUMENTATION
        - value: PRODUCT_OR_SERVICE_DESCRIPTION
        - value: RECEIPT
        - value: SERVICE_RECEIVED_DOCUMENTATION
        - value: PROOF_OF_DELIVERY_DOCUMENTATION
        - value: RELATED_TRANSACTION_DOCUMENTATION
        - value: REBUTTAL_EXPLANATION
        - value: TRACKING_NUMBER
    DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceFileContentType:
      type: string
      enum:
        - value: application/pdf
        - value: image/png
        - value: image/jpeg
        - value: image/heic
        - value: image/heif
        - value: image/tiff
    DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceFile:
      type: object
      properties:
        filename:
          type: string
          description: >-
            Name of the uploaded file. It should be descriptive enough to
            indicate what type of information is contained in the uploaded file.
        content_type:
          $ref: >-
            #/components/schemas/DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceFileContentType
          description: |-
            The MIME type of the uploaded file.

            Current values:

            - `application/pdf`
            - `image/heic`
            - `image/heif`
            - `image/jpeg`
            - `image/png`
            - `image/tiff`
      required:
        - filename
        - content_type
    Metadata:
      type: object
      additionalProperties:
        type: string
    DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidence:
      type: object
      properties:
        category:
          $ref: >-
            #/components/schemas/DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceCategory
          description: >-
            Describes what type of information is contained in this piece of
            evidence.


            Current values:


            - `GENERIC_EVIDENCE`: Default evidence type used if no other
            category applies.

            - `ONLINE_OR_APP_ACCESS_LOG`: Server or activity logs that show
            proof of the cardholder’s identity and that the cardholder
            successfully ordered and received the goods (digitally or
            otherwise). Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholder’s name and email address linked to a
            cardholder profile held by the seller, proof the same device and
            card (used in dispute) were previously used in prior undisputed
            transaction, and any related detailed activity.

            - `AUTHORIZATION_DOCUMENTATION`: **[File Only]** Evidence that the
            cardholder did provide authorization for the charge. Example
            evidence includes a signed credit card authorization.

            - `CANCELLATION_OR_REFUND_DOCUMENTATION`: Evidence that the
            cardholder acknowledged your refund or cancellation policy. Example
            evidence includes a signature or checkbox showing the cardholder’s
            acknowledgement of your refund or cancellation policy.

            - `CARDHOLDER_COMMUNICATION`: **[File Only]** Evidence that shows
            relevant communication with the cardholder. Example evidence
            includes emails or texts that show the cardholder received
            goods/services or demonstrate cardholder satisfaction.

            - `CARDHOLDER_INFORMATION`: Evidence that validates the customer's
            identity. Example evidence includes personally identifiable details
            such as name, email address, purchaser IP address, and a copy of the
            cardholder ID.

            - `PURCHASE_ACKNOWLEDGEMENT`: Evidence that shows proof of the
            sale/transaction. Example evidence includes an invoice, contract, or
            other item showing the customer’s acknowledgement of the purchase
            and your terms.

            - `DUPLICATE_CHARGE_DOCUMENTATION`: **[File Only]** Evidence that
            shows the charges in question are valid and distinct from one
            another. Example evidence includes receipts, shipping labels, and
            invoices along with their distinct payment IDs.

            - `PRODUCT_OR_SERVICE_DESCRIPTION`: A description of the product or
            service sold.

            - `RECEIPT`: A receipt or message sent to the cardholder detailing
            the charge. Note: You do not need to upload the Square receipt;
            Square submits the receipt on your behalf.

            - `SERVICE_RECEIVED_DOCUMENTATION`: Evidence that the service was
            provided to the cardholder or the expected date that services will
            be rendered. Example evidence includes a signed delivery form, work
            order, expected delivery date, or other written agreements.

            - `PROOF_OF_DELIVERY_DOCUMENTATION`: Evidence that shows the product
            was provided to the cardholder or the expected date of delivery.
            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.

            - `RELATED_TRANSACTION_DOCUMENTATION`: Evidence that shows the
            cardholder previously processed transactions on the same card and
            did not dispute them.

            - `REBUTTAL_EXPLANATION`: An explanation of why the cardholder’s
            claim is invalid. Example evidence includes an explanation of why
            each distinct charge is a legitimate purchase, why the cardholder’s
            claim for credit owed due to their attempt to cancel, return, or
            refund is invalid per your stated policy and cardholder agreement,
            or an explanation of how the cardholder did not attempt to remedy
            the issue with you first to receive credit.

            - `TRACKING_NUMBER`: The tracking number for the order provided by
            the shipping carrier. If you have multiple numbers, they need to be
            submitted individually as separate pieces of evidence.
        file:
          $ref: >-
            #/components/schemas/DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceFile
          description: Metadata about the uploaded file.
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - category
        - file
    DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequest:
      type: object
      properties:
        idempotency_key:
          $ref: '#/components/schemas/IdempotencyKey'
        evidence:
          $ref: >-
            #/components/schemas/DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidence
          description: Details about the evidence to create.
    DisputeEvidenceCategory:
      type: string
      enum:
        - value: GENERIC_EVIDENCE
        - value: ONLINE_OR_APP_ACCESS_LOG
        - value: AUTHORIZATION_DOCUMENTATION
        - value: CANCELLATION_OR_REFUND_DOCUMENTATION
        - value: CARDHOLDER_COMMUNICATION
        - value: CARDHOLDER_INFORMATION
        - value: PURCHASE_ACKNOWLEDGEMENT
        - value: DUPLICATE_CHARGE_DOCUMENTATION
        - value: PRODUCT_OR_SERVICE_DESCRIPTION
        - value: RECEIPT
        - value: SERVICE_RECEIVED_DOCUMENTATION
        - value: PROOF_OF_DELIVERY_DOCUMENTATION
        - value: RELATED_TRANSACTION_DOCUMENTATION
        - value: REBUTTAL_EXPLANATION
        - value: TRACKING_NUMBER
    DisputeEvidenceFileContentType:
      type: string
      enum:
        - value: application/pdf
        - value: image/heic
        - value: image/heif
        - value: image/jpeg
        - value: image/png
        - value: image/tiff
    DisputeEvidenceFile:
      type: object
      properties:
        filename:
          type: string
          description: >-
            Name of the uploaded file. It should be descriptive enough to
            indicate what type of information is contained in the uploaded file.
        content_type:
          $ref: '#/components/schemas/DisputeEvidenceFileContentType'
          description: |-
            The MIME type of the uploaded file.

            Current values:

            - `application/pdf`
            - `image/heic`
            - `image/heif`
            - `image/jpeg`
            - `image/png`
            - `image/tiff`
      required:
        - filename
        - content_type
    DisputeEvidenceType:
      type: string
      enum:
        - value: FILE
        - value: TEXT
    DisputeEvidence:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute evidence issued by Cash App.

            Min length: `1`
            Max length: `128`
        dispute_id:
          type: string
          description: |-
            ID of the dispute this evidence is associated with.

            Min length: `1`
            Max length: `128`
        category:
          $ref: '#/components/schemas/DisputeEvidenceCategory'
          description: >-
            Describes what type of information is contained in this piece of
            evidence.


            Current values:


            - `GENERIC_EVIDENCE`: Default evidence type used if no other
            category applies.

            - `ONLINE_OR_APP_ACCESS_LOG`: Server or activity logs that show
            proof of the cardholder’s identity and that the cardholder
            successfully ordered and received the goods (digitally or
            otherwise). Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholder’s name and email address linked to a
            cardholder profile held by the seller, proof the same device and
            card (used in dispute) were previously used in prior undisputed
            transaction, and any related detailed activity.

            - `AUTHORIZATION_DOCUMENTATION`: **[File Only]** Evidence that the
            cardholder did provide authorization for the charge. Example
            evidence includes a signed credit card authorization.

            - `CANCELLATION_OR_REFUND_DOCUMENTATION`: Evidence that the
            cardholder acknowledged your refund or cancellation policy. Example
            evidence includes a signature or checkbox showing the cardholder’s
            acknowledgement of your refund or cancellation policy.

            - `CARDHOLDER_COMMUNICATION`: **[File Only]** Evidence that shows
            relevant communication with the cardholder. Example evidence
            includes emails or texts that show the cardholder received
            goods/services or demonstrate cardholder satisfaction.

            - `CARDHOLDER_INFORMATION`: Evidence that validates the customer's
            identity. Example evidence includes personally identifiable details
            such as name, email address, purchaser IP address, and a copy of the
            cardholder ID.

            - `PURCHASE_ACKNOWLEDGEMENT`: Evidence that shows proof of the
            sale/transaction. Example evidence includes an invoice, contract, or
            other item showing the customer’s acknowledgement of the purchase
            and your terms.

            - `DUPLICATE_CHARGE_DOCUMENTATION`: **[File Only]** Evidence that
            shows the charges in question are valid and distinct from one
            another. Example evidence includes receipts, shipping labels, and
            invoices along with their distinct payment IDs.

            - `PRODUCT_OR_SERVICE_DESCRIPTION`: A description of the product or
            service sold.

            - `RECEIPT`: A receipt or message sent to the cardholder detailing
            the charge. Note: You do not need to upload the Square receipt;
            Square submits the receipt on your behalf.

            - `SERVICE_RECEIVED_DOCUMENTATION`: Evidence that the service was
            provided to the cardholder or the expected date that services will
            be rendered. Example evidence includes a signed delivery form, work
            order, expected delivery date, or other written agreements.

            - `PROOF_OF_DELIVERY_DOCUMENTATION`: Evidence that shows the product
            was provided to the cardholder or the expected date of delivery.
            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.

            - `RELATED_TRANSACTION_DOCUMENTATION`: Evidence that shows the
            cardholder previously processed transactions on the same card and
            did not dispute them.

            - `REBUTTAL_EXPLANATION`: An explanation of why the cardholder’s
            claim is invalid. Example evidence includes an explanation of why
            each distinct charge is a legitimate purchase, why the cardholder’s
            claim for credit owed due to their attempt to cancel, return, or
            refund is invalid per your stated policy and cardholder agreement,
            or an explanation of how the cardholder did not attempt to remedy
            the issue with you first to receive credit.

            - `TRACKING_NUMBER`: The tracking number for the order provided by
            the shipping carrier. If you have multiple numbers, they need to be
            submitted individually as separate pieces of evidence.
        file:
          $ref: '#/components/schemas/DisputeEvidenceFile'
          description: >-
            If the evidence is of type `FILE`, contains metadata about the
            binary file uploaded as evidence.
        text:
          type: string
          description: >-
            If the evidence is of type `TEXT`, contains the blob of text created
            as evidence.


            Min length: `1`

            Max length: `500`
        type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: |-
            Indicates if the evidence is a file or plain text.

            Current values:
            - `TEXT`: The evidence is a blob of text under 500 characters.
            - `FILE`: The evidence is an uploaded binary file.
        created_at:
          type: string
          format: date-time
          description: >-
            When this evidence was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - dispute_id
        - category
        - type
        - created_at
    Disputes_create-dispute-evidence-file_Response_201:
      type: object
      properties:
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
      required:
        - evidence

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence-file"

files = { "file": "open('string', 'rb')" }
payload = { "request": "{
  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",
  \"evidence\": {
    \"category\": \"GENERIC_EVIDENCE\",
    \"file\": {
      \"filename\": \"filename\",
      \"content_type\": \"application/pdf\"
    }
  }
}" }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-file';
const form = new FormData();
form.append('request', '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": {
    "category": "GENERIC_EVIDENCE",
    "file": {
      "filename": "filename",
      "content_type": "application/pdf"
    }
  }
}');
form.append('file', 'string');

const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence-file"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence-file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/disputes/dispute_id/evidence-file")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-file', [
  'multipart' => [
    [
        'name' => 'request',
        'contents' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": {
    "category": "GENERIC_EVIDENCE",
    "file": {
      "filename": "filename",
      "content_type": "application/pdf"
    }
  }
}'
    ],
    [
        'name' => 'file',
        'filename' => 'string',
        'contents' => null
    ]
  ]
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence-file");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]
let parameters = [
  [
    "name": "request",
    "value": "{
  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",
  \"evidence\": {
    \"category\": \"GENERIC_EVIDENCE\",
    \"file\": {
      \"filename\": \"filename\",
      \"content_type\": \"application/pdf\"
    }
  }
}"
  ],
  [
    "name": "file",
    "fileName": "string"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence-file")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence-file"

files = { "file": "open('string', 'rb')" }
payload = { "request": "{
  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",
  \"evidence\": {
    \"category\": \"GENERIC_EVIDENCE\",
    \"file\": {
      \"filename\": \"filename\",
      \"content_type\": \"application/pdf\"
    },
    \"metadata\": {
      \"key\": \"value\"
    }
  }
}" }
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-file';
const form = new FormData();
form.append('request', '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": {
    "category": "GENERIC_EVIDENCE",
    "file": {
      "filename": "filename",
      "content_type": "application/pdf"
    },
    "metadata": {
      "key": "value"
    }
  }
}');
form.append('file', 'string');

const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence-file"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    },\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence-file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    },\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/network/v1/disputes/dispute_id/evidence-file")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    },\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence-file', [
  'multipart' => [
    [
        'name' => 'request',
        'contents' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "evidence": {
    "category": "GENERIC_EVIDENCE",
    "file": {
      "filename": "filename",
      "content_type": "application/pdf"
    },
    "metadata": {
      "key": "value"
    }
  }
}'
    ],
    [
        'name' => 'file',
        'filename' => 'string',
        'contents' => null
    ]
  ]
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence-file");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"request\"\r\n\r\n{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"evidence\": {\n    \"category\": \"GENERIC_EVIDENCE\",\n    \"file\": {\n      \"filename\": \"filename\",\n      \"content_type\": \"application/pdf\"\n    },\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]
let parameters = [
  [
    "name": "request",
    "value": "{
  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",
  \"evidence\": {
    \"category\": \"GENERIC_EVIDENCE\",
    \"file\": {
      \"filename\": \"filename\",
      \"content_type\": \"application/pdf\"
    },
    \"metadata\": {
      \"key\": \"value\"
    }
  }
}"
  ],
  [
    "name": "file",
    "fileName": "string"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence-file")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Delete dispute evidence

DELETE https://api.cash.app/network/v1/disputes/{dispute_id}/evidence/{evidence_id}

Deletes a piece of dispute evidence by the ID of the dispute its for and its own ID.

**This endpoint is not rate limited.**

Scopes: `DISPUTES_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/delete-dispute-evidence

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete dispute evidence
  version: endpoint_disputes.delete-dispute-evidence
paths:
  /disputes/{dispute_id}/evidence/{evidence_id}:
    delete:
      operationId: delete-dispute-evidence
      summary: Delete dispute evidence
      description: >-
        Deletes a piece of dispute evidence by the ID of the dispute its for and
        its own ID.


        **This endpoint is not rate limited.**


        Scopes: `DISPUTES_WRITE`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: evidence_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Disputes_delete-dispute-evidence_Response_200
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    Disputes_delete-dispute-evidence_Response_200:
      type: object
      properties: {}

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.delete(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id';
const options = {
  method: 'DELETE',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve dispute evidence

GET https://api.cash.app/network/v1/disputes/{dispute_id}/evidence/{evidence_id}

Retrieves a piece of dispute evidence by the ID of the dispute its for and its own ID.

**This endpoint is not rate limited.**

Scopes: `DISPUTES_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-dispute-evidence

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve dispute evidence
  version: endpoint_disputes.retrieve-dispute-evidence
paths:
  /disputes/{dispute_id}/evidence/{evidence_id}:
    get:
      operationId: retrieve-dispute-evidence
      summary: Retrieve dispute evidence
      description: >-
        Retrieves a piece of dispute evidence by the ID of the dispute its for
        and its own ID.


        **This endpoint is not rate limited.**


        Scopes: `DISPUTES_READ`
      tags:
        - - subpackage_disputes
      parameters:
        - name: dispute_id
          in: path
          required: true
          schema:
            type: string
        - name: evidence_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Disputes_retrieve-dispute-evidence_Response_200
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    DisputeEvidenceCategory:
      type: string
      enum:
        - value: GENERIC_EVIDENCE
        - value: ONLINE_OR_APP_ACCESS_LOG
        - value: AUTHORIZATION_DOCUMENTATION
        - value: CANCELLATION_OR_REFUND_DOCUMENTATION
        - value: CARDHOLDER_COMMUNICATION
        - value: CARDHOLDER_INFORMATION
        - value: PURCHASE_ACKNOWLEDGEMENT
        - value: DUPLICATE_CHARGE_DOCUMENTATION
        - value: PRODUCT_OR_SERVICE_DESCRIPTION
        - value: RECEIPT
        - value: SERVICE_RECEIVED_DOCUMENTATION
        - value: PROOF_OF_DELIVERY_DOCUMENTATION
        - value: RELATED_TRANSACTION_DOCUMENTATION
        - value: REBUTTAL_EXPLANATION
        - value: TRACKING_NUMBER
    DisputeEvidenceFileContentType:
      type: string
      enum:
        - value: application/pdf
        - value: image/heic
        - value: image/heif
        - value: image/jpeg
        - value: image/png
        - value: image/tiff
    DisputeEvidenceFile:
      type: object
      properties:
        filename:
          type: string
          description: >-
            Name of the uploaded file. It should be descriptive enough to
            indicate what type of information is contained in the uploaded file.
        content_type:
          $ref: '#/components/schemas/DisputeEvidenceFileContentType'
          description: |-
            The MIME type of the uploaded file.

            Current values:

            - `application/pdf`
            - `image/heic`
            - `image/heif`
            - `image/jpeg`
            - `image/png`
            - `image/tiff`
      required:
        - filename
        - content_type
    DisputeEvidenceType:
      type: string
      enum:
        - value: FILE
        - value: TEXT
    Metadata:
      type: object
      additionalProperties:
        type: string
    DisputeEvidence:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute evidence issued by Cash App.

            Min length: `1`
            Max length: `128`
        dispute_id:
          type: string
          description: |-
            ID of the dispute this evidence is associated with.

            Min length: `1`
            Max length: `128`
        category:
          $ref: '#/components/schemas/DisputeEvidenceCategory'
          description: >-
            Describes what type of information is contained in this piece of
            evidence.


            Current values:


            - `GENERIC_EVIDENCE`: Default evidence type used if no other
            category applies.

            - `ONLINE_OR_APP_ACCESS_LOG`: Server or activity logs that show
            proof of the cardholder’s identity and that the cardholder
            successfully ordered and received the goods (digitally or
            otherwise). Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholder’s name and email address linked to a
            cardholder profile held by the seller, proof the same device and
            card (used in dispute) were previously used in prior undisputed
            transaction, and any related detailed activity.

            - `AUTHORIZATION_DOCUMENTATION`: **[File Only]** Evidence that the
            cardholder did provide authorization for the charge. Example
            evidence includes a signed credit card authorization.

            - `CANCELLATION_OR_REFUND_DOCUMENTATION`: Evidence that the
            cardholder acknowledged your refund or cancellation policy. Example
            evidence includes a signature or checkbox showing the cardholder’s
            acknowledgement of your refund or cancellation policy.

            - `CARDHOLDER_COMMUNICATION`: **[File Only]** Evidence that shows
            relevant communication with the cardholder. Example evidence
            includes emails or texts that show the cardholder received
            goods/services or demonstrate cardholder satisfaction.

            - `CARDHOLDER_INFORMATION`: Evidence that validates the customer's
            identity. Example evidence includes personally identifiable details
            such as name, email address, purchaser IP address, and a copy of the
            cardholder ID.

            - `PURCHASE_ACKNOWLEDGEMENT`: Evidence that shows proof of the
            sale/transaction. Example evidence includes an invoice, contract, or
            other item showing the customer’s acknowledgement of the purchase
            and your terms.

            - `DUPLICATE_CHARGE_DOCUMENTATION`: **[File Only]** Evidence that
            shows the charges in question are valid and distinct from one
            another. Example evidence includes receipts, shipping labels, and
            invoices along with their distinct payment IDs.

            - `PRODUCT_OR_SERVICE_DESCRIPTION`: A description of the product or
            service sold.

            - `RECEIPT`: A receipt or message sent to the cardholder detailing
            the charge. Note: You do not need to upload the Square receipt;
            Square submits the receipt on your behalf.

            - `SERVICE_RECEIVED_DOCUMENTATION`: Evidence that the service was
            provided to the cardholder or the expected date that services will
            be rendered. Example evidence includes a signed delivery form, work
            order, expected delivery date, or other written agreements.

            - `PROOF_OF_DELIVERY_DOCUMENTATION`: Evidence that shows the product
            was provided to the cardholder or the expected date of delivery.
            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.

            - `RELATED_TRANSACTION_DOCUMENTATION`: Evidence that shows the
            cardholder previously processed transactions on the same card and
            did not dispute them.

            - `REBUTTAL_EXPLANATION`: An explanation of why the cardholder’s
            claim is invalid. Example evidence includes an explanation of why
            each distinct charge is a legitimate purchase, why the cardholder’s
            claim for credit owed due to their attempt to cancel, return, or
            refund is invalid per your stated policy and cardholder agreement,
            or an explanation of how the cardholder did not attempt to remedy
            the issue with you first to receive credit.

            - `TRACKING_NUMBER`: The tracking number for the order provided by
            the shipping carrier. If you have multiple numbers, they need to be
            submitted individually as separate pieces of evidence.
        file:
          $ref: '#/components/schemas/DisputeEvidenceFile'
          description: >-
            If the evidence is of type `FILE`, contains metadata about the
            binary file uploaded as evidence.
        text:
          type: string
          description: >-
            If the evidence is of type `TEXT`, contains the blob of text created
            as evidence.


            Min length: `1`

            Max length: `500`
        type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: |-
            Indicates if the evidence is a file or plain text.

            Current values:
            - `TEXT`: The evidence is a blob of text under 500 characters.
            - `FILE`: The evidence is an uploaded binary file.
        created_at:
          type: string
          format: date-time
          description: >-
            When this evidence was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - id
        - dispute_id
        - category
        - type
        - created_at
    Disputes_retrieve-dispute-evidence_Response_200:
      type: object
      properties:
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
      required:
        - evidence

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/disputes/dispute_id/evidence/evidence_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Dispute

<EndpointSchemaSnippet endpoint="POST /disputes/:dispute_id/accept" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "DSPT_1fbjn9dg7rmz1xeyv6gkyh8vg",
    "payment_id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
    "amount": 1500,
    "customer_credited_amount": 1250,
    "reason": "FR10",
    "settlement_withholding": "NOT_WITHHELD",
    "state": "RESPONSE_REQUIRED",
    "created_at": "2022-01-01T12:00:00Z",
    "response_due_at": "2022-05-01T00:00:00Z",
    "updated_at": "2022-01-05T12:00:00Z",
    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x"
  }
  ```
</Aside>

---

# DisputeEvidence

<EndpointSchemaSnippet endpoint="POST /disputes/{dispute_id}/evidence-text" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "EVD_dbdda8e161b7bad8519f7f73",
    "dispute_id": "DSPT_1fbjn9dg7rmz1xeyv6gkyh8vg",
    "category": "GENERIC_EVIDENCE",
    "file": {
      "filename": "string",
      "content_type": "application/pdf"
    },
    "text": "string",
    "type": "FILE",
    "created_at": "2022-01-01T12:00:00Z",
    "metadata": {
      "my-meta": "meta-value"
    }
  }
  ```
</Aside>

---

# Event: dispute.created

POST 

**When is this event triggered?**

This event is created whenever a dispute is created. This is caused by a customer filing a dispute concerning a payment collected by a merchant managed by this API client.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/dispute-created

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: dispute.created'
  version: subpackage_disputes.disputeCreated
webhooks:
  dispute-created:
    post:
      operationId: dispute-created
      summary: 'Event: dispute.created'
      description: >-
        **When is this event triggered?**


        This event is created whenever a dispute is created. This is caused by a
        customer filing a dispute concerning a payment collected by a merchant
        managed by this API client.
      tags:
        - subpackage_disputes
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `dispute.created` for this
                    event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaData
                  description: Data about the dispute that was created.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        dispute:
          $ref: '#/components/schemas/Dispute'
      required:
        - dispute
    WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the dispute.
        object:
          $ref: >-
            #/components/schemas/WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaDataObject
          description: A snapshot of the dispute immediately after the dispute was created.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `dispute`.
      required:
        - id
        - object
        - type

```

---

# Event: dispute.status.updated

POST 

**When is this event triggered?**

This event is created whenever a dispute's state is updated. This can be caused by a variety of things:
  - An API client-driven change where the dispute is accepted or challenged
  - Cash App Pay making a final decision on a dispute

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/dispute-status-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: dispute.status.updated'
  version: subpackage_disputes.disputeStatusUpdated
webhooks:
  dispute-status-updated:
    post:
      operationId: dispute-status-updated
      summary: 'Event: dispute.status.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a dispute's state is updated. This can be
        caused by a variety of things:
          - An API client-driven change where the dispute is accepted or challenged
          - Cash App Pay making a final decision on a dispute
      tags:
        - subpackage_disputes
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred. `dispute.status.updated`
                    for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the dispute that was updated.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        dispute:
          $ref: '#/components/schemas/Dispute'
      required:
        - dispute
    WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the dispute.
        object:
          $ref: >-
            #/components/schemas/WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the dispute immediately after the dispute's status was
            updated.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `dispute`.
      required:
        - id
        - object
        - type

```

---

# Retrieve Fee Plan

GET https://api.cash.app/network/v1/fee-plans/{fee_plan_id}

Retrieves a fee plan by its ID.

**This endpoint is not rate limited.**

Scopes: `FEE_PLANS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/retrieve-fee-plan

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve Fee Plan
  version: endpoint_feePlans.retrieve-fee-plan
paths:
  /fee-plans/{fee_plan_id}:
    get:
      operationId: retrieve-fee-plan
      summary: Retrieve Fee Plan
      description: |-
        Retrieves a fee plan by its ID.

        **This endpoint is not rate limited.**

        Scopes: `FEE_PLANS_READ`
      tags:
        - - subpackage_feePlans
      parameters:
        - name: fee_plan_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee Plans_retrieve-fee-plan_Response_200'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    Currency:
      type: string
      enum:
        - value: USD
    Metadata:
      type: object
      additionalProperties:
        type: string
    FeePlan:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the fee plan issued by Cash App.
        rate:
          $ref: '#/components/schemas/FeeRate'
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          type: string
          description: >-
            The state is used to determine whether or not this fee plan is
            currently in use.

            - `ACTIVE`

            - `DISABLED`
        reference_id:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
        description:
          type: string
          description: >-
            A free-form text field that stores information associated with the
            fee plan.
        created_at:
          type: string
          format: date-time
          description: >-
            When this fee plan was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this fee plan was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - rate
        - currency
        - status
        - created_at
        - updated_at
    Fee Plans_retrieve-fee-plan_Response_200:
      type: object
      properties:
        fee_plan:
          $ref: '#/components/schemas/FeePlan'
      required:
        - fee_plan

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/fee-plans/fee_plan_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/fee-plans/fee_plan_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/fee-plans/fee_plan_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/fee-plans/fee_plan_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/fee-plans/fee_plan_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/fee-plans/fee_plan_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/fee-plans/fee_plan_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/fee-plans/fee_plan_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# List fee plans

GET https://api.cash.app/network/v1/fee-plans

Returns a list of all fee plans (matching the given query parameters) associated with this client.

**This endpoint is rate limited to 50 QPS.**

Scopes: `FEE_PLANS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/network-api/list-fee-plans

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List fee plans
  version: endpoint_feePlans.list-fee-plans
paths:
  /fee-plans:
    get:
      operationId: list-fee-plans
      summary: List fee plans
      description: >-
        Returns a list of all fee plans (matching the given query parameters)
        associated with this client.


        **This endpoint is rate limited to 50 QPS.**


        Scopes: `FEE_PLANS_READ`
      tags:
        - - subpackage_feePlans
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of fee plans to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: currency
          in: query
          description: >-
            Filters results to only include fee plans that matches the the given
            currency.
          required: false
          schema:
            $ref: '#/components/schemas/Currency'
        - name: status
          in: query
          description: >-
            Filters results to only include fee plans that matches the the given
            status.
          required: false
          schema:
            $ref: '#/components/schemas/FeePlansGetParametersStatus'
        - name: reference_id
          in: query
          description: >-
            Filters results to only include the fee plans that match the given
            reference ID.
          required: false
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fee Plans_list-fee-plans_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    FeePlansGetParametersStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: DISABLED
      default: ACTIVE
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    Metadata:
      type: object
      additionalProperties:
        type: string
    FeePlan:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the fee plan issued by Cash App.
        rate:
          $ref: '#/components/schemas/FeeRate'
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          type: string
          description: >-
            The state is used to determine whether or not this fee plan is
            currently in use.

            - `ACTIVE`

            - `DISABLED`
        reference_id:
          type: string
        metadata:
          $ref: '#/components/schemas/Metadata'
        description:
          type: string
          description: >-
            A free-form text field that stores information associated with the
            fee plan.
        created_at:
          type: string
          format: date-time
          description: >-
            When this fee plan was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this fee plan was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - rate
        - currency
        - status
        - created_at
        - updated_at
    Fee Plans_list-fee-plans_Response_200:
      type: object
      properties:
        fee_plans:
          type: array
          items:
            $ref: '#/components/schemas/FeePlan'
          description: List of fee plans matching the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/network/v1/fee-plans"

querystring = {"cursor":"string"}

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/network/v1/fee-plans?cursor=string';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/network/v1/fee-plans?cursor=string"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/network/v1/fee-plans?cursor=string")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/network/v1/fee-plans?cursor=string")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/network/v1/fee-plans?cursor=string', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/network/v1/fee-plans?cursor=string");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/network/v1/fee-plans?cursor=string")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# FeeRate

<EndpointSchemaSnippet endpoint="GET /fee-rate-schema" selector="response.body" />

<Aside>
  ```json Example
  {
    "basis_points": 160,
    "fixed_amount": 20
  }
  ```
</Aside>

---

# FeePlan

<EndpointSchemaSnippet endpoint="GET /fee-plan-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "FEE_kewjsmjt35t8qhzyjeqcst5me",
    "rate": {
      "basis_points": 160,
      "fixed_amount": 20
    },
    "currency": "USD",
    "status": "ACTIVE",
    "reference_id": "external-id",
    "metadata": {},
    "created_at": "2023-01-01T12:00:00Z",
    "updated_at": "2023-01-01T12:00:00Z"
  }
  ```
</Aside>

---

# Address

<EndpointSchemaSnippet endpoint="GET /address-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "address_line_1": "1215 4th Ave",
    "address_line_2": "Suite 2300",
    "locality": "Seattle",
    "country": "US",
    "postal_code": "98161-1001",
    "administrative_district_level_1": "Washington"
  }
  ```
</Aside>

---

# Authorization

<EndpointSchemaSnippet endpoint="GET /authorization-schema" selector="response.body" />

<Aside>
  ```json Example
  {
    "authorization_code": "AUTH_123456",
    "authorized_at": "2021-01-01T00:00:00Z",
    "authorized_amount": 1000
  }
  ```
</Aside>

---

# Category

<EndpointSchemaSnippet endpoint="GET /category-schema-test" selector="response.body" />

<Aside>
  ```json Example
  5432
  ```
</Aside>

---

# Country

<EndpointSchemaSnippet endpoint="GET /country-schema-test" selector="response.body" />

<Aside>
  ```json Example
  US
  ```
</Aside>

---

# Currency

<EndpointSchemaSnippet endpoint="GET /currency-schema-test" selector="response.body" />

<Aside>
  ```json Example
  USD
  ```
</Aside>

---

# Grant

<EndpointSchemaSnippet endpoint="GET /grant-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
    "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
    "request_id": "GRR_1hrxhz136krcq6ezdte2ha5q",
    "action": {
      "amount": 2500,
      "currency": "USD",
      "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
      "type": "ONE_TIME_PAYMENT"
    },
    "status": "ACTIVE",
    "type": "ONE_TIME",
    "channel": "ONLINE",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "expires_at": "2022-04-01T12:00:00Z"
  }
  ```
</Aside>

---

# Idempotency_key

<EndpointSchemaSnippet endpoint="GET /idempotency-key-schema-test" selector="response.body" />

<Aside>
  ```json Example
  e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19
  ```
</Aside>

---

# Metadata

<EndpointSchemaSnippet endpoint="GET /metadata-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "my-meta": "meta-value",
  }
  ```
</Aside>

---

# Error

<EndpointSchemaSnippet endpoint="GET /error-schema" selector="response.body" />

<Aside>
  ```json Example
  {
    "category": "INVALID_REQUEST_ERROR",
    "code": "MISSING_REQUIRED_FIELD",
    "detail": "Missing required parameter.",
    "field": "field_a[2].field_b"
  }
  ```
</Aside>

---

# ErrorResponse

<EndpointSchemaSnippet endpoint="GET /error-response-schema" selector="response.body" />

<Aside>
  ```json Example
  {
    "errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "MISSING_REQUIRED_FIELD",
        "detail": "Missing required parameter.",
        "field": "field_a[2].field_b"
      }
    ]
  }
  ```
</Aside>

---

# ValidateOrderAmountsParam

<EndpointSchemaSnippet endpoint="GET /validate-order-amounts-param-schema-test" selector="response.body" />

<Aside>
  ```json Example
  false
  ```
</Aside>

---

# Create request

POST https://api.cash.app/customer-request/v1/requests
Content-Type: application/json

Creates a request to perform an action on a customer's account. All available actions can be found in the `action` schema.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/customer-request-api/create-request

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create request
  version: endpoint_requests.create-request
paths:
  /requests:
    post:
      operationId: create-request
      summary: Create request
      description: >-
        Creates a request to perform an action on a customer's account. All
        available actions can be found in the `action` schema.
      tags:
        - - subpackage_requests
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requests_create-request_Response_201'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                request:
                  $ref: >-
                    #/components/schemas/RequestsPostRequestBodyContentApplicationJsonSchemaRequest
                  description: Details about the request to create.
              required:
                - idempotency_key
                - request
components:
  schemas:
    IdempotencyKey:
      type: string
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    RequestsPostRequestBodyContentApplicationJsonSchemaRequestChannel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Metadata:
      type: object
      additionalProperties:
        type: string
    CustomerMetadata:
      type: object
      properties:
        reference_id:
          type: string
          description: >-
            The `reference_id` of the customer approving this request. When a
            customer approves this request, that customer will be associated
            with this `reference_id`.
    RequestsPostRequestBodyContentApplicationJsonSchemaRequest:
      type: object
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            A list of the different actions a client intends to take on the
            customer if the request is approved.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        channel:
          $ref: >-
            #/components/schemas/RequestsPostRequestBodyContentApplicationJsonSchemaRequestChannel
          description: >-
            How the customer is expected to interact with the request.


            - `IN_PERSON`: The customer presents or scans a QR code at a
            physical location to approve the request.

            - `ONLINE`: The customer scans a QR code or is redirected to Cash
            App from a browser context.

            - `IN_APP`: The customer scans a QR code or is redirected to Cash
            App from a native mobile application context.
        redirect_url:
          type: string
          format: uri
          description: >-
            If this request is responded to via mobile redirect, this field
            specifies the URL that Cash App will open for a customer in the
            mobile device's default browser after the request is approved or
            declined.
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        customer_metadata:
          $ref: '#/components/schemas/CustomerMetadata'
      required:
        - actions
        - channel
    RequestStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
        - value: PENDING
        - value: PROCESSING
      default: PENDING
    RequestAuthFlowTriggers:
      type: object
      properties:
        qr_code_image_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as a PNG file.


            Min length: `8`

            Max length: `1024`
        qr_code_svg_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as an SVG file.


            Min length: `8`

            Max length: `1024`
        mobile_url:
          type: string
          format: uri
          description: >-
            If on an Android or iOS device, the URL to redirect customers to in
            order to authorize the given action.


            Min length: `8`

            Max length: `1024`
        refreshes_at:
          type: string
          format: date-time
          description: >-
            When the QR code image URL will be rotated. Generally, it will
            rotate every ~20 seconds and become invalid after 30 seconds.
        desktop_url:
          type: string
          format: uri
          description: >-
            If on a desktop browser, the URL to redirect customers to in order
            to authorize the given action.


            Min length: `8`

            Max length: `1024`
      required:
        - qr_code_image_url
        - qr_code_svg_url
        - mobile_url
        - refreshes_at
    RequestOriginType:
      type: string
      enum:
        - value: DIRECT
        - value: REQUEST_INITIATOR
    RequestOrigin:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RequestOriginType'
          description: >-
            The method used to create the customer request.


            - `DIRECT` - the client or SDKs created this customer request by
            calling the "CreateCustomerRequest" endpoint

            - `REQUEST_INITIATOR` - a customer interacted with a request
            initiator and caused Cash App to create a customer request.
        id:
          type: string
          description: |-
            If present, is the ID of the initiator used to create this request.

            Min length: `1`
            Max length: `128`
      required:
        - type
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    RequestRequesterProfile:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        logo_url:
          type: string
          format: uri
          description: >-
            URL to the image of the entity (brand or client) that is requesting
            permission to perform the actions on the customer request.


            Formats:

            - `.jpg`

            - `.jpeg`

            - `.png`


            Min length: `8`

            Max length: `8000`
      required:
        - name
        - logo_url
    RequestCustomerProfile:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - cashtag
    Request:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the request issued by Cash App.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RequestStatus'
          description: >-
            Indicates if the state is approved, declined, or pending. Approved
            requests have grants, while pending and declined grants do not.


            Current values:


            - `PENDING`: The request has been created, but not responded to.

            - `PROCESSING`: The Cash App customer is actively responding to the
            request on their mobile device, and will require time to fill out
            information before the request is approved / declined.

            - `APPROVED`: The request was approved by the customer and grants
            have been created for the provided actions.

            - `DECLINED`: The request was denied by the customer. No grants were
            created.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            Represents what the client intends to do to a customer if given
            authorization.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        auth_flow_triggers:
          $ref: '#/components/schemas/RequestAuthFlowTriggers'
          description: >-
            While the request is `PENDING`, contains different methods that can
            be used to start

            the authorization flow in the Cash App mobile application. Its
            contents refresh each time

            the `refreshes_at` timestamp passes. When the

            data refreshes, you should update any buttons

            or QR codes referring to it immediately.


            After a request has been scanned (and is no

            longer in the `PENDING` status), this

            field will no longer be returned.
        redirect_url:
          type: string
          format: uri
          description: >-
            If this request is responded to via mobile redirect, this field
            specifies the URL that Cash App will open for a customer in the
            mobile device's default browser after the request is approved or
            declined.
        created_at:
          type: string
          format: date-time
          description: >-
            When this customer request was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When the customer request was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this customer request will be automatically declined by Cash
            App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
            format (UTC).
        origin:
          $ref: '#/components/schemas/RequestOrigin'
          description: Metadata describing how the customer request was created.
        channel:
          $ref: '#/components/schemas/Channel'
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: >-
            If present, contains grants that can be used to perform actions
            specified in the request using the Network API.


            Each grant corresponds directly to an action on the request.


            Min number of items: `1`

            Max number of items: `5`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        requester_profile:
          $ref: '#/components/schemas/RequestRequesterProfile'
          description: >-
            Details about the brand or client that are requesting permission to
            perform the actions on the customer request.
        customer_profile:
          $ref: '#/components/schemas/RequestCustomerProfile'
          description: >-
            If the customer request was approved, contains the identity of the
            Cash App customer that approved it.
        metadata:
          $ref: '#/components/schemas/Metadata'
        customer_metadata:
          $ref: '#/components/schemas/CustomerMetadata'
      required:
        - id
        - status
        - actions
        - redirect_url
        - created_at
        - updated_at
        - expires_at
        - origin
        - channel
    Requests_create-request_Response_201:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/Request'
      required:
        - request

```

## SDK Code Examples

```python Request with One Time Payment Action
import requests

url = "https://api.cash.app/customer-request/v1/requests"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Request with One Time Payment Action
const url = 'https://api.cash.app/customer-request/v1/requests';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with One Time Payment Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with One Time Payment Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Request with One Time Payment Action
HttpResponse<String> response = Unirest.post("https://api.cash.app/customer-request/v1/requests")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Request with One Time Payment Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/customer-request/v1/requests', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with One Time Payment Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Request with One Time Payment Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with On File Payment Action
import requests

url = "https://api.cash.app/customer-request/v1/requests"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Request with On File Payment Action
const url = 'https://api.cash.app/customer-request/v1/requests';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with On File Payment Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with On File Payment Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Request with On File Payment Action
HttpResponse<String> response = Unirest.post("https://api.cash.app/customer-request/v1/requests")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Request with On File Payment Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/customer-request/v1/requests', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with On File Payment Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Request with On File Payment Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with Link Account Action
import requests

url = "https://api.cash.app/customer-request/v1/requests"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Request with Link Account Action
const url = 'https://api.cash.app/customer-request/v1/requests';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with Link Account Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with Link Account Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Request with Link Account Action
HttpResponse<String> response = Unirest.post("https://api.cash.app/customer-request/v1/requests")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Request with Link Account Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/customer-request/v1/requests', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with Link Account Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Request with Link Account Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Sample request with metadata
import requests

url = "https://api.cash.app/customer-request/v1/requests"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "request": {
        "actions": [
            {
                "amount": 2500,
                "currency": "USD",
                "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
                "type": "ONE_TIME_PAYMENT"
            }
        ],
        "channel": "IN_PERSON",
        "redirect_url": "https://example.com",
        "reference_id": "string",
        "metadata": { "key": "value" },
        "customer_metadata": { "reference_id": "string" }
    }
}
headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Sample request with metadata
const url = 'https://api.cash.app/customer-request/v1/requests';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","request":{"actions":[{"amount":2500,"currency":"USD","scope_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","type":"ONE_TIME_PAYMENT"}],"channel":"IN_PERSON","redirect_url":"https://example.com","reference_id":"string","metadata":{"key":"value"},"customer_metadata":{"reference_id":"string"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Sample request with metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Sample request with metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Sample request with metadata
HttpResponse<String> response = Unirest.post("https://api.cash.app/customer-request/v1/requests")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}")
  .asString();
```

```php Sample request with metadata
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/customer-request/v1/requests', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "request": {
    "actions": [
      {
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      }
    ],
    "channel": "IN_PERSON",
    "redirect_url": "https://example.com",
    "reference_id": "string",
    "metadata": {
      "key": "value"
    },
    "customer_metadata": {
      "reference_id": "string"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Sample request with metadata
var client = new RestClient("https://api.cash.app/customer-request/v1/requests");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    },\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request with metadata
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "request": [
    "actions": [
      [
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      ]
    ],
    "channel": "IN_PERSON",
    "redirect_url": "https://example.com",
    "reference_id": "string",
    "metadata": ["key": "value"],
    "customer_metadata": ["reference_id": "string"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Sample request without metadata
import requests

url = "https://api.cash.app/customer-request/v1/requests"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "request": {
        "actions": [
            {
                "amount": 2500,
                "currency": "USD",
                "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
                "type": "ONE_TIME_PAYMENT"
            }
        ],
        "channel": "IN_PERSON",
        "redirect_url": "https://example.com",
        "reference_id": "string",
        "customer_metadata": { "reference_id": "string" }
    }
}
headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Sample request without metadata
const url = 'https://api.cash.app/customer-request/v1/requests';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","request":{"actions":[{"amount":2500,"currency":"USD","scope_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","type":"ONE_TIME_PAYMENT"}],"channel":"IN_PERSON","redirect_url":"https://example.com","reference_id":"string","customer_metadata":{"reference_id":"string"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Sample request without metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Sample request without metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Sample request without metadata
HttpResponse<String> response = Unirest.post("https://api.cash.app/customer-request/v1/requests")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}")
  .asString();
```

```php Sample request without metadata
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/customer-request/v1/requests', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "request": {
    "actions": [
      {
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      }
    ],
    "channel": "IN_PERSON",
    "redirect_url": "https://example.com",
    "reference_id": "string",
    "customer_metadata": {
      "reference_id": "string"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Sample request without metadata
var client = new RestClient("https://api.cash.app/customer-request/v1/requests");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"channel\": \"IN_PERSON\",\n    \"redirect_url\": \"https://example.com\",\n    \"reference_id\": \"string\",\n    \"customer_metadata\": {\n      \"reference_id\": \"string\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request without metadata
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "request": [
    "actions": [
      [
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      ]
    ],
    "channel": "IN_PERSON",
    "redirect_url": "https://example.com",
    "reference_id": "string",
    "customer_metadata": ["reference_id": "string"]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve request

GET https://api.cash.app/customer-request/v1/requests/{request_id}

Retrieves a customer request by its ID.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/customer-request-api/retrieve-request

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve request
  version: endpoint_requests.retrieve-request
paths:
  /requests/{request_id}:
    get:
      operationId: retrieve-request
      summary: Retrieve request
      description: Retrieves a customer request by its ID.
      tags:
        - - subpackage_requests
      parameters:
        - name: request_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requests_retrieve-request_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    RequestStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
        - value: PENDING
        - value: PROCESSING
      default: PENDING
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    RequestAuthFlowTriggers:
      type: object
      properties:
        qr_code_image_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as a PNG file.


            Min length: `8`

            Max length: `1024`
        qr_code_svg_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as an SVG file.


            Min length: `8`

            Max length: `1024`
        mobile_url:
          type: string
          format: uri
          description: >-
            If on an Android or iOS device, the URL to redirect customers to in
            order to authorize the given action.


            Min length: `8`

            Max length: `1024`
        refreshes_at:
          type: string
          format: date-time
          description: >-
            When the QR code image URL will be rotated. Generally, it will
            rotate every ~20 seconds and become invalid after 30 seconds.
        desktop_url:
          type: string
          format: uri
          description: >-
            If on a desktop browser, the URL to redirect customers to in order
            to authorize the given action.


            Min length: `8`

            Max length: `1024`
      required:
        - qr_code_image_url
        - qr_code_svg_url
        - mobile_url
        - refreshes_at
    RequestOriginType:
      type: string
      enum:
        - value: DIRECT
        - value: REQUEST_INITIATOR
    RequestOrigin:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RequestOriginType'
          description: >-
            The method used to create the customer request.


            - `DIRECT` - the client or SDKs created this customer request by
            calling the "CreateCustomerRequest" endpoint

            - `REQUEST_INITIATOR` - a customer interacted with a request
            initiator and caused Cash App to create a customer request.
        id:
          type: string
          description: |-
            If present, is the ID of the initiator used to create this request.

            Min length: `1`
            Max length: `128`
      required:
        - type
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    RequestRequesterProfile:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        logo_url:
          type: string
          format: uri
          description: >-
            URL to the image of the entity (brand or client) that is requesting
            permission to perform the actions on the customer request.


            Formats:

            - `.jpg`

            - `.jpeg`

            - `.png`


            Min length: `8`

            Max length: `8000`
      required:
        - name
        - logo_url
    RequestCustomerProfile:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - cashtag
    Metadata:
      type: object
      additionalProperties:
        type: string
    CustomerMetadata:
      type: object
      properties:
        reference_id:
          type: string
          description: >-
            The `reference_id` of the customer approving this request. When a
            customer approves this request, that customer will be associated
            with this `reference_id`.
    Request:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the request issued by Cash App.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RequestStatus'
          description: >-
            Indicates if the state is approved, declined, or pending. Approved
            requests have grants, while pending and declined grants do not.


            Current values:


            - `PENDING`: The request has been created, but not responded to.

            - `PROCESSING`: The Cash App customer is actively responding to the
            request on their mobile device, and will require time to fill out
            information before the request is approved / declined.

            - `APPROVED`: The request was approved by the customer and grants
            have been created for the provided actions.

            - `DECLINED`: The request was denied by the customer. No grants were
            created.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            Represents what the client intends to do to a customer if given
            authorization.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        auth_flow_triggers:
          $ref: '#/components/schemas/RequestAuthFlowTriggers'
          description: >-
            While the request is `PENDING`, contains different methods that can
            be used to start

            the authorization flow in the Cash App mobile application. Its
            contents refresh each time

            the `refreshes_at` timestamp passes. When the

            data refreshes, you should update any buttons

            or QR codes referring to it immediately.


            After a request has been scanned (and is no

            longer in the `PENDING` status), this

            field will no longer be returned.
        redirect_url:
          type: string
          format: uri
          description: >-
            If this request is responded to via mobile redirect, this field
            specifies the URL that Cash App will open for a customer in the
            mobile device's default browser after the request is approved or
            declined.
        created_at:
          type: string
          format: date-time
          description: >-
            When this customer request was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When the customer request was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this customer request will be automatically declined by Cash
            App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
            format (UTC).
        origin:
          $ref: '#/components/schemas/RequestOrigin'
          description: Metadata describing how the customer request was created.
        channel:
          $ref: '#/components/schemas/Channel'
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: >-
            If present, contains grants that can be used to perform actions
            specified in the request using the Network API.


            Each grant corresponds directly to an action on the request.


            Min number of items: `1`

            Max number of items: `5`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        requester_profile:
          $ref: '#/components/schemas/RequestRequesterProfile'
          description: >-
            Details about the brand or client that are requesting permission to
            perform the actions on the customer request.
        customer_profile:
          $ref: '#/components/schemas/RequestCustomerProfile'
          description: >-
            If the customer request was approved, contains the identity of the
            Cash App customer that approved it.
        metadata:
          $ref: '#/components/schemas/Metadata'
        customer_metadata:
          $ref: '#/components/schemas/CustomerMetadata'
      required:
        - id
        - status
        - actions
        - redirect_url
        - created_at
        - updated_at
        - expires_at
        - origin
        - channel
    Requests_retrieve-request_Response_200:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/Request'
      required:
        - request

```

## SDK Code Examples

```python Request with One Time Payment Action
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Request with One Time Payment Action
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {method: 'GET', headers: {Accept: 'Accept', 'User-Agent': 'User-Agent'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with One Time Payment Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with One Time Payment Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java Request with One Time Payment Action
HttpResponse<String> response = Unirest.get("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php Request with One Time Payment Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with One Time Payment Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift Request with One Time Payment Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with On File Payment Action
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Request with On File Payment Action
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {method: 'GET', headers: {Accept: 'Accept', 'User-Agent': 'User-Agent'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with On File Payment Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with On File Payment Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java Request with On File Payment Action
HttpResponse<String> response = Unirest.get("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php Request with On File Payment Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with On File Payment Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift Request with On File Payment Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with Link Account Action
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Request with Link Account Action
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {method: 'GET', headers: {Accept: 'Accept', 'User-Agent': 'User-Agent'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with Link Account Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with Link Account Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java Request with Link Account Action
HttpResponse<String> response = Unirest.get("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php Request with Link Account Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with Link Account Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift Request with Link Account Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with One Time Payment Action and Grant
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Request with One Time Payment Action and Grant
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {method: 'GET', headers: {Accept: 'Accept', 'User-Agent': 'User-Agent'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with One Time Payment Action and Grant
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with One Time Payment Action and Grant
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java Request with One Time Payment Action and Grant
HttpResponse<String> response = Unirest.get("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php Request with One Time Payment Action and Grant
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with One Time Payment Action and Grant
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift Request with One Time Payment Action and Grant
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with On File Payment Action and Grant
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Request with On File Payment Action and Grant
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {method: 'GET', headers: {Accept: 'Accept', 'User-Agent': 'User-Agent'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with On File Payment Action and Grant
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with On File Payment Action and Grant
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java Request with On File Payment Action and Grant
HttpResponse<String> response = Unirest.get("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php Request with On File Payment Action and Grant
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with On File Payment Action and Grant
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift Request with On File Payment Action and Grant
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with Link Account Action and Grant
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Request with Link Account Action and Grant
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {method: 'GET', headers: {Accept: 'Accept', 'User-Agent': 'User-Agent'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with Link Account Action and Grant
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with Link Account Action and Grant
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java Request with Link Account Action and Grant
HttpResponse<String> response = Unirest.get("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php Request with Link Account Action and Grant
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with Link Account Action and Grant
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift Request with Link Account Action and Grant
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Update request

PATCH https://api.cash.app/customer-request/v1/requests/{request_id}
Content-Type: application/json

Updates a customer request. The request must have its `status` in a `PENDING` state to successfully update.

To clear a field, set it to `null`. Fields that are not provided in the request will not be changed.
If updating an array field, the entire contents of the array must be passed.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/customer-request-api/update-request

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update request
  version: endpoint_requests.update-request
paths:
  /requests/{request_id}:
    patch:
      operationId: update-request
      summary: Update request
      description: >-
        Updates a customer request. The request must have its `status` in a
        `PENDING` state to successfully update.


        To clear a field, set it to `null`. Fields that are not provided in the
        request will not be changed.

        If updating an array field, the entire contents of the array must be
        passed.
      tags:
        - - subpackage_requests
      parameters:
        - name: request_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requests_update-request_Response_200'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                request:
                  $ref: >-
                    #/components/schemas/RequestsRequestIdPatchRequestBodyContentApplicationJsonSchemaRequest
                  description: Details about the request to update
              required:
                - request
components:
  schemas:
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    Metadata:
      type: object
      additionalProperties:
        type: string
    RequestsRequestIdPatchRequestBodyContentApplicationJsonSchemaRequest:
      type: object
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            A list of the different actions a client intends to take on the
            customer if the request is approved.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        reference_id:
          type:
            - string
            - 'null'
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
    RequestStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
        - value: PENDING
        - value: PROCESSING
      default: PENDING
    RequestAuthFlowTriggers:
      type: object
      properties:
        qr_code_image_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as a PNG file.


            Min length: `8`

            Max length: `1024`
        qr_code_svg_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as an SVG file.


            Min length: `8`

            Max length: `1024`
        mobile_url:
          type: string
          format: uri
          description: >-
            If on an Android or iOS device, the URL to redirect customers to in
            order to authorize the given action.


            Min length: `8`

            Max length: `1024`
        refreshes_at:
          type: string
          format: date-time
          description: >-
            When the QR code image URL will be rotated. Generally, it will
            rotate every ~20 seconds and become invalid after 30 seconds.
        desktop_url:
          type: string
          format: uri
          description: >-
            If on a desktop browser, the URL to redirect customers to in order
            to authorize the given action.


            Min length: `8`

            Max length: `1024`
      required:
        - qr_code_image_url
        - qr_code_svg_url
        - mobile_url
        - refreshes_at
    RequestOriginType:
      type: string
      enum:
        - value: DIRECT
        - value: REQUEST_INITIATOR
    RequestOrigin:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RequestOriginType'
          description: >-
            The method used to create the customer request.


            - `DIRECT` - the client or SDKs created this customer request by
            calling the "CreateCustomerRequest" endpoint

            - `REQUEST_INITIATOR` - a customer interacted with a request
            initiator and caused Cash App to create a customer request.
        id:
          type: string
          description: |-
            If present, is the ID of the initiator used to create this request.

            Min length: `1`
            Max length: `128`
      required:
        - type
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    RequestRequesterProfile:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        logo_url:
          type: string
          format: uri
          description: >-
            URL to the image of the entity (brand or client) that is requesting
            permission to perform the actions on the customer request.


            Formats:

            - `.jpg`

            - `.jpeg`

            - `.png`


            Min length: `8`

            Max length: `8000`
      required:
        - name
        - logo_url
    RequestCustomerProfile:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - cashtag
    CustomerMetadata:
      type: object
      properties:
        reference_id:
          type: string
          description: >-
            The `reference_id` of the customer approving this request. When a
            customer approves this request, that customer will be associated
            with this `reference_id`.
    Request:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the request issued by Cash App.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RequestStatus'
          description: >-
            Indicates if the state is approved, declined, or pending. Approved
            requests have grants, while pending and declined grants do not.


            Current values:


            - `PENDING`: The request has been created, but not responded to.

            - `PROCESSING`: The Cash App customer is actively responding to the
            request on their mobile device, and will require time to fill out
            information before the request is approved / declined.

            - `APPROVED`: The request was approved by the customer and grants
            have been created for the provided actions.

            - `DECLINED`: The request was denied by the customer. No grants were
            created.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            Represents what the client intends to do to a customer if given
            authorization.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        auth_flow_triggers:
          $ref: '#/components/schemas/RequestAuthFlowTriggers'
          description: >-
            While the request is `PENDING`, contains different methods that can
            be used to start

            the authorization flow in the Cash App mobile application. Its
            contents refresh each time

            the `refreshes_at` timestamp passes. When the

            data refreshes, you should update any buttons

            or QR codes referring to it immediately.


            After a request has been scanned (and is no

            longer in the `PENDING` status), this

            field will no longer be returned.
        redirect_url:
          type: string
          format: uri
          description: >-
            If this request is responded to via mobile redirect, this field
            specifies the URL that Cash App will open for a customer in the
            mobile device's default browser after the request is approved or
            declined.
        created_at:
          type: string
          format: date-time
          description: >-
            When this customer request was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When the customer request was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this customer request will be automatically declined by Cash
            App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
            format (UTC).
        origin:
          $ref: '#/components/schemas/RequestOrigin'
          description: Metadata describing how the customer request was created.
        channel:
          $ref: '#/components/schemas/Channel'
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: >-
            If present, contains grants that can be used to perform actions
            specified in the request using the Network API.


            Each grant corresponds directly to an action on the request.


            Min number of items: `1`

            Max number of items: `5`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        requester_profile:
          $ref: '#/components/schemas/RequestRequesterProfile'
          description: >-
            Details about the brand or client that are requesting permission to
            perform the actions on the customer request.
        customer_profile:
          $ref: '#/components/schemas/RequestCustomerProfile'
          description: >-
            If the customer request was approved, contains the identity of the
            Cash App customer that approved it.
        metadata:
          $ref: '#/components/schemas/Metadata'
        customer_metadata:
          $ref: '#/components/schemas/CustomerMetadata'
      required:
        - id
        - status
        - actions
        - redirect_url
        - created_at
        - updated_at
        - expires_at
        - origin
        - channel
    Requests_update-request_Response_200:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/Request'
      required:
        - request

```

## SDK Code Examples

```python Request with One Time Payment Action
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, headers=headers)

print(response.json())
```

```javascript Request with One Time Payment Action
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with One Time Payment Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with One Time Payment Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Request with One Time Payment Action
HttpResponse<String> response = Unirest.patch("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Request with One Time Payment Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with One Time Payment Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Request with One Time Payment Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with On File Payment Action
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, headers=headers)

print(response.json())
```

```javascript Request with On File Payment Action
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with On File Payment Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with On File Payment Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Request with On File Payment Action
HttpResponse<String> response = Unirest.patch("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Request with On File Payment Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with On File Payment Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Request with On File Payment Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Request with Link Account Action
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, headers=headers)

print(response.json())
```

```javascript Request with Link Account Action
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request with Link Account Action
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	req, _ := http.NewRequest("PATCH", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request with Link Account Action
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Request with Link Account Action
HttpResponse<String> response = Unirest.patch("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .asString();
```

```php Request with Link Account Action
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Request with Link Account Action
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Request with Link Account Action
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Sample request with metadata
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

payload = { "request": {
        "actions": [
            {
                "amount": 2500,
                "currency": "USD",
                "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
                "type": "ONE_TIME_PAYMENT"
            }
        ],
        "reference_id": "string",
        "metadata": { "key": "value" }
    } }
headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Sample request with metadata
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"request":{"actions":[{"amount":2500,"currency":"USD","scope_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","type":"ONE_TIME_PAYMENT"}],"reference_id":"string","metadata":{"key":"value"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Sample request with metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	payload := strings.NewReader("{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Sample request with metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Sample request with metadata
HttpResponse<String> response = Unirest.patch("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}")
  .asString();
```

```php Sample request with metadata
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'body' => '{
  "request": {
    "actions": [
      {
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      }
    ],
    "reference_id": "string",
    "metadata": {
      "key": "value"
    }
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Sample request with metadata
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\",\n    \"metadata\": {\n      \"key\": \"value\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request with metadata
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["request": [
    "actions": [
      [
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      ]
    ],
    "reference_id": "string",
    "metadata": ["key": "value"]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Sample request without metadata
import requests

url = "https://api.cash.app/customer-request/v1/requests/request_id"

payload = { "request": {
        "actions": [
            {
                "amount": 2500,
                "currency": "USD",
                "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
                "type": "ONE_TIME_PAYMENT"
            }
        ],
        "reference_id": "string"
    } }
headers = {
    "Accept": "Accept",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript Sample request without metadata
const url = 'https://api.cash.app/customer-request/v1/requests/request_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"request":{"actions":[{"amount":2500,"currency":"USD","scope_id":"MMI_4vxs5egfk7hmta3qx2h6rp91x","type":"ONE_TIME_PAYMENT"}],"reference_id":"string"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Sample request without metadata
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/customer-request/v1/requests/request_id"

	payload := strings.NewReader("{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Sample request without metadata
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/customer-request/v1/requests/request_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Sample request without metadata
HttpResponse<String> response = Unirest.patch("https://api.cash.app/customer-request/v1/requests/request_id")
  .header("Accept", "Accept")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\"\n  }\n}")
  .asString();
```

```php Sample request without metadata
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/customer-request/v1/requests/request_id', [
  'body' => '{
  "request": {
    "actions": [
      {
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      }
    ],
    "reference_id": "string"
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
  ],
]);

echo $response->getBody();
```

```csharp Sample request without metadata
var client = new RestClient("https://api.cash.app/customer-request/v1/requests/request_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"request\": {\n    \"actions\": [\n      {\n        \"amount\": 2500,\n        \"currency\": \"USD\",\n        \"scope_id\": \"MMI_4vxs5egfk7hmta3qx2h6rp91x\",\n        \"type\": \"ONE_TIME_PAYMENT\"\n      }\n    ],\n    \"reference_id\": \"string\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Sample request without metadata
import Foundation

let headers = [
  "Accept": "Accept",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = ["request": [
    "actions": [
      [
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      ]
    ],
    "reference_id": "string"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/customer-request/v1/requests/request_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Event: customer_request.state.updated

POST 

**When is this event triggered?**

This event is created whenever a customer request's state is updated. This is typically caused by a customer approving or declining the request.

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/customer-request-api/customer-request-state-updated

## OpenAPI 3.1 Webhook Specification

```yaml
openapi: 3.1.1
info:
  title: 'Event: customer_request.state.updated'
  version: subpackage_requests.customerRequestStateUpdated
webhooks:
  customer-request-state-updated:
    post:
      operationId: customer-request-state-updated
      summary: 'Event: customer_request.state.updated'
      description: >-
        **When is this event triggered?**


        This event is created whenever a customer request's state is updated.
        This is typically caused by a customer approving or declining the
        request.
      tags:
        - subpackage_requests
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    The type of event that occurred.
                    `customer_request.state.updated` for this event.
                event_id:
                  type: string
                  description: A unique identifier provided by Cash App for the event.
                created_at:
                  type: string
                  format: date-time
                  description: >-
                    When this event occured in [RFC
                    3339](https://datatracker.ietf.org/doc/html/rfc3339) format
                    (UTC).


                    The time that the event is delivered may be significantly
                    later than this timestamp due to webhooks being retried for
                    up to 72 hours.
                data:
                  $ref: >-
                    #/components/schemas/WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaData
                  description: Data about the customer request that was updated.
              required:
                - type
                - event_id
                - created_at
                - data
components:
  schemas:
    RequestStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
        - value: PENDING
        - value: PROCESSING
      default: PENDING
    Currency:
      type: string
      enum:
        - value: USD
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    RequestAuthFlowTriggers:
      type: object
      properties:
        qr_code_image_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as a PNG file.


            Min length: `8`

            Max length: `1024`
        qr_code_svg_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as an SVG file.


            Min length: `8`

            Max length: `1024`
        mobile_url:
          type: string
          format: uri
          description: >-
            If on an Android or iOS device, the URL to redirect customers to in
            order to authorize the given action.


            Min length: `8`

            Max length: `1024`
        refreshes_at:
          type: string
          format: date-time
          description: >-
            When the QR code image URL will be rotated. Generally, it will
            rotate every ~20 seconds and become invalid after 30 seconds.
        desktop_url:
          type: string
          format: uri
          description: >-
            If on a desktop browser, the URL to redirect customers to in order
            to authorize the given action.


            Min length: `8`

            Max length: `1024`
      required:
        - qr_code_image_url
        - qr_code_svg_url
        - mobile_url
        - refreshes_at
    RequestOriginType:
      type: string
      enum:
        - value: DIRECT
        - value: REQUEST_INITIATOR
    RequestOrigin:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RequestOriginType'
          description: >-
            The method used to create the customer request.


            - `DIRECT` - the client or SDKs created this customer request by
            calling the "CreateCustomerRequest" endpoint

            - `REQUEST_INITIATOR` - a customer interacted with a request
            initiator and caused Cash App to create a customer request.
        id:
          type: string
          description: |-
            If present, is the ID of the initiator used to create this request.

            Min length: `1`
            Max length: `128`
      required:
        - type
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    RequestRequesterProfile:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        logo_url:
          type: string
          format: uri
          description: >-
            URL to the image of the entity (brand or client) that is requesting
            permission to perform the actions on the customer request.


            Formats:

            - `.jpg`

            - `.jpeg`

            - `.png`


            Min length: `8`

            Max length: `8000`
      required:
        - name
        - logo_url
    RequestCustomerProfile:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - cashtag
    Metadata:
      type: object
      additionalProperties:
        type: string
    CustomerMetadata:
      type: object
      properties:
        reference_id:
          type: string
          description: >-
            The `reference_id` of the customer approving this request. When a
            customer approves this request, that customer will be associated
            with this `reference_id`.
    Request:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the request issued by Cash App.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RequestStatus'
          description: >-
            Indicates if the state is approved, declined, or pending. Approved
            requests have grants, while pending and declined grants do not.


            Current values:


            - `PENDING`: The request has been created, but not responded to.

            - `PROCESSING`: The Cash App customer is actively responding to the
            request on their mobile device, and will require time to fill out
            information before the request is approved / declined.

            - `APPROVED`: The request was approved by the customer and grants
            have been created for the provided actions.

            - `DECLINED`: The request was denied by the customer. No grants were
            created.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            Represents what the client intends to do to a customer if given
            authorization.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        auth_flow_triggers:
          $ref: '#/components/schemas/RequestAuthFlowTriggers'
          description: >-
            While the request is `PENDING`, contains different methods that can
            be used to start

            the authorization flow in the Cash App mobile application. Its
            contents refresh each time

            the `refreshes_at` timestamp passes. When the

            data refreshes, you should update any buttons

            or QR codes referring to it immediately.


            After a request has been scanned (and is no

            longer in the `PENDING` status), this

            field will no longer be returned.
        redirect_url:
          type: string
          format: uri
          description: >-
            If this request is responded to via mobile redirect, this field
            specifies the URL that Cash App will open for a customer in the
            mobile device's default browser after the request is approved or
            declined.
        created_at:
          type: string
          format: date-time
          description: >-
            When this customer request was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When the customer request was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this customer request will be automatically declined by Cash
            App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
            format (UTC).
        origin:
          $ref: '#/components/schemas/RequestOrigin'
          description: Metadata describing how the customer request was created.
        channel:
          $ref: '#/components/schemas/Channel'
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: >-
            If present, contains grants that can be used to perform actions
            specified in the request using the Network API.


            Each grant corresponds directly to an action on the request.


            Min number of items: `1`

            Max number of items: `5`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        requester_profile:
          $ref: '#/components/schemas/RequestRequesterProfile'
          description: >-
            Details about the brand or client that are requesting permission to
            perform the actions on the customer request.
        customer_profile:
          $ref: '#/components/schemas/RequestCustomerProfile'
          description: >-
            If the customer request was approved, contains the identity of the
            Cash App customer that approved it.
        metadata:
          $ref: '#/components/schemas/Metadata'
        customer_metadata:
          $ref: '#/components/schemas/CustomerMetadata'
      required:
        - id
        - status
        - actions
        - redirect_url
        - created_at
        - updated_at
        - expires_at
        - origin
        - channel
    WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaDataObject:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/Request'
      required:
        - request
    WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaData:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier provided by Cash App for the customer request.
        object:
          $ref: >-
            #/components/schemas/WebhooksCustomerRequestStateUpdatedPayloadContentApplicationJsonSchemaDataObject
          description: >-
            A snapshot of the customer request data immediately after the
            customer request's state was updated.
        type:
          type: string
          description: >-
            The resource type contained in the `object` field. For this event,
            it is `customer_request`.
      required:
        - id
        - object
        - type

```

---

# Action

<EndpointSchemaSnippet endpoint="GET /action-schema-test" selector="response" />

<Aside>
  ```json Example
  {
    "amount": 2500,
    "currency": "USD",
    "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "type": "ONE_TIME_PAYMENT"
  }
  ```
</Aside>

---

# Request

<EndpointSchemaSnippet endpoint="POST /requests" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "GRR_1hrxhz136krcq6ezdte2ha5q",
    "status": "PENDING",
    "actions": [
      {
        "amount": 2500,
        "currency": "USD",
        "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
        "type": "ONE_TIME_PAYMENT"
      }
    ],
    "auth_flow_triggers": {
      "qr_code_image_url": "https://api.cash.app/qr/f/GRANTLY_MANAGED_GRANT%3Frequest_id=GRR_1hrxhz136krcq6ezdte2ha5q-k21srg&method=qr?rounded=0&format=png",
      "qr_code_svg_url": "https://api.cash.app/qr/f/GRANTLY_MANAGED_GRANT%3Frequest_id=GRR_1hrxhz136krcq6ezdte2ha5q-k21srg&method=qr?rounded=0&format=svg",
      "mobile_url": "https://cash.app/f/GRANTLY_MANAGED_GRANT%3Frequest_id=GRR_1hrxhz136krcq6ezdte2ha5q-k21srg&method=mobile_url",
      "refreshes_at": "2019-08-24T14:15:22Z",
      "desktop_url": "https://pay.cash.app?customerRequestId={request_id}"
    },
    "redirect_url": "https://example.com",
    "created_at": "2022-01-01T12:09:00Z",
    "updated_at": "2022-01-01T12:10:00Z",
    "expires_at": "2033-01-01T12:20:00Z",
    "origin": {
      "type": "DIRECT",
      "id": "string"
    },
    "channel": "ONLINE",
    "grants": [
      {
        "id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
        "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
        "action": {
          "amount": 2500,
          "currency": "USD",
          "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
          "type": "ONE_TIME_PAYMENT"
        },
        "status": "ACTIVE",
        "type": "ONE_TIME",
        "channel": "ONLINE",
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "expires_at": "2022-04-01T12:00:00Z"
      }
    ],
    "reference_id": "external-id",
    "requester_profile": {
      "name": "A Brand",
      "logo_url": "https://picsum.photos/200"
    },
    "customer_profile": {
      "id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
      "cashtag": "$CashTag"
    },
    "metadata": {},
    "customer_metadata": {
      "reference_id": "string"
    }
  }
  ```
</Aside>

---

# Link Account Action

<EndpointSchemaSnippet endpoint="GET /link-account-action-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "type": "LINK_ACCOUNT"
  }
  ```
</Aside>

---

# One Time Payment Action

<EndpointSchemaSnippet endpoint="GET /one-time-payment-action-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "amount": 2500,
    "currency": "USD",
    "scope_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
    "type": "ONE_TIME_PAYMENT"
  }
  ```
</Aside>

---

# On File Payment Action

<EndpointSchemaSnippet endpoint="GET /on-file-payment-action-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "scope_id": "BRAND_8ereg0tug2yiik8vx24xpe5br",
    "type": "ON_FILE_PAYMENT",
    "account_reference_id": "string"
  }
  ```
</Aside>

---

# Channel

<EndpointSchemaSnippet endpoint="GET /channel-schema-test" selector="response.body" />

<Aside>
  ```json Example
  ONLINE
  ```
</Aside>

---

# Customer Metadata

<EndpointSchemaSnippet endpoint="GET /customer-metadata-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "reference_id": "external-id"
  }
  ```
</Aside>

---

# ErrorResponse

<EndpointSchemaSnippet endpoint="GET /error-response-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "MISSING_REQUIRED_FIELD",
        "detail": "Missing required parameter.",
        "field": "field_a[2].field_b"
      }
    ]
  }
  ```
</Aside>

---

# List API keys

GET https://api.cash.app/management/v1/api-keys

Returns a list of active API keys matching the given query parameters.

**This endpoint is rate limited to 5 QPS.**

Scopes: `API_KEYS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/list-api-keys

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List API keys
  version: endpoint_apiKeys.list-api-keys
paths:
  /api-keys:
    get:
      operationId: list-api-keys
      summary: List API keys
      description: |-
        Returns a list of active API keys matching the given query parameters.

        **This endpoint is rate limited to 5 QPS.**

        Scopes: `API_KEYS_READ`
      tags:
        - - subpackage_apiKeys
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of API keys to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_list-api-keys_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    ScopesItems:
      type: string
      enum:
        - value: PAYMENTS_READ
        - value: PAYMENTS_WRITE
        - value: REFUNDS_READ
        - value: REFUNDS_WRITE
        - value: DISPUTES_READ
        - value: DISPUTES_WRITE
        - value: CUSTOMERS_READ
        - value: FEE_PLANS_READ
        - value: GRANTS_READ
        - value: GRANTS_WRITE
        - value: API_KEYS_READ
        - value: API_KEYS_WRITE
        - value: BRANDS_READ
        - value: BRANDS_WRITE
        - value: MERCHANTS_READ
        - value: MERCHANTS_WRITE
        - value: WEBHOOK_CONFIG_READ
        - value: WEBHOOK_CONFIG_WRITE
        - value: WEBHOOK_EVENTS_READ
    Scopes:
      type: array
      items:
        $ref: '#/components/schemas/ScopesItems'
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for this API key issued by Cash App. This is the
            API key value that is passed in the `Authorization` header.
        created_at:
          type: string
          format: date-time
          description: >-
            When this API key was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this API key will be automatically deleted and become unusable,
            in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format
            (UTC).
        scopes:
          $ref: '#/components/schemas/Scopes'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this API key, typically used to
            associate the API key with a record in an external system.


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - created_at
        - expires_at
        - scopes
    apiKeys_list-api-keys_Response_200:
      type: object
      properties:
        api_keys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKey'
          description: List of API keys for the given query parameters.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - api_keys

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/api-keys"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/api-keys';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/api-keys"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/api-keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/management/v1/api-keys")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/management/v1/api-keys', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/api-keys");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/api-keys")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create API key

POST https://api.cash.app/management/v1/api-keys
Content-Type: application/json

Creates a new API key and secret to use in the `Authorization` and `X-Signature` headers for requests to the Cash App Pay API. This key will automatically expire at the date and time specified in the `expires_at` field in the response payload.

<Note title="Note">
 The `secret` returned in the response payload is what you use to calculate the `X-Signature` header. The API key ID is only used to keep track of which API keys are active, and isn't considered secret.
 Keep in mind that the `secret` can never be retrieved in subsequent requests to the API, so make sure to store it immediately!
</Note>
**This endpoint is rate limited to 5 QPS.**

Scopes: `API_KEYS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/create-api-key

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create API key
  version: endpoint_apiKeys.create-api-key
paths:
  /api-keys:
    post:
      operationId: create-api-key
      summary: Create API key
      description: >-
        Creates a new API key and secret to use in the `Authorization` and
        `X-Signature` headers for requests to the Cash App Pay API. This key
        will automatically expire at the date and time specified in the
        `expires_at` field in the response payload.


        <Note title="Note">
         The `secret` returned in the response payload is what you use to calculate the `X-Signature` header. The API key ID is only used to keep track of which API keys are active, and isn't considered secret.
         Keep in mind that the `secret` can never be retrieved in subsequent requests to the API, so make sure to store it immediately!
        </Note>

        **This endpoint is rate limited to 5 QPS.**


        Scopes: `API_KEYS_WRITE`
      tags:
        - - subpackage_apiKeys
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_create-api-key_Response_201'
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                api_key:
                  $ref: >-
                    #/components/schemas/ApiKeysPostRequestBodyContentApplicationJsonSchemaApiKey
                  description: Details about the API key to create.
              required:
                - idempotency_key
                - api_key
components:
  schemas:
    IdempotencyKey:
      type: string
    ScopesItems:
      type: string
      enum:
        - value: PAYMENTS_READ
        - value: PAYMENTS_WRITE
        - value: REFUNDS_READ
        - value: REFUNDS_WRITE
        - value: DISPUTES_READ
        - value: DISPUTES_WRITE
        - value: CUSTOMERS_READ
        - value: FEE_PLANS_READ
        - value: GRANTS_READ
        - value: GRANTS_WRITE
        - value: API_KEYS_READ
        - value: API_KEYS_WRITE
        - value: BRANDS_READ
        - value: BRANDS_WRITE
        - value: MERCHANTS_READ
        - value: MERCHANTS_WRITE
        - value: WEBHOOK_CONFIG_READ
        - value: WEBHOOK_CONFIG_WRITE
        - value: WEBHOOK_EVENTS_READ
    Scopes:
      type: array
      items:
        $ref: '#/components/schemas/ScopesItems'
    ApiKeysPostRequestBodyContentApplicationJsonSchemaApiKey:
      type: object
      properties:
        scopes:
          $ref: '#/components/schemas/Scopes'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this API key, typically used to
            associate the API key with a record in an external system.


            Min length: `1`

            Max length: `1024`
      required:
        - scopes
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for this API key issued by Cash App. This is the
            API key value that is passed in the `Authorization` header.
        created_at:
          type: string
          format: date-time
          description: >-
            When this API key was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this API key will be automatically deleted and become unusable,
            in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format
            (UTC).
        scopes:
          $ref: '#/components/schemas/Scopes'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this API key, typically used to
            associate the API key with a record in an external system.


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - created_at
        - expires_at
        - scopes
    apiKeys_create-api-key_Response_201:
      type: object
      properties:
        api_key:
          $ref: '#/components/schemas/ApiKey'
        secret:
          type: string
          description: >-
            Secret value to use when calculating the `X-Signature` header of
            requests.


            This value is not returned when retrieving an API key, so make sure
            to store it immediately.


            Min length: `32`

            Max length: `256`
      required:
        - api_key
        - secret

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/api-keys"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "api_key": { "scopes": ["PAYMENTS_READ"] }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/api-keys';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","api_key":{"scopes":["PAYMENTS_READ"]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/api-keys"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"api_key\": {\n    \"scopes\": [\n      \"PAYMENTS_READ\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/api-keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"api_key\": {\n    \"scopes\": [\n      \"PAYMENTS_READ\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/api-keys")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"api_key\": {\n    \"scopes\": [\n      \"PAYMENTS_READ\"\n    ]\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/api-keys', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "api_key": {
    "scopes": [
      "PAYMENTS_READ"
    ]
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/api-keys");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"api_key\": {\n    \"scopes\": [\n      \"PAYMENTS_READ\"\n    ]\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "api_key": ["scopes": ["PAYMENTS_READ"]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/api-keys")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve API key

GET https://api.cash.app/management/v1/api-keys/{api_key_id}

Retrieves an API key by ID.

**This endpoint is rate limited to 10 QPS.**

Scopes: `API_KEYS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/retrieve-api-key

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve API key
  version: endpoint_apiKeys.retrieve-api-key
paths:
  /api-keys/{api_key_id}:
    get:
      operationId: retrieve-api-key
      summary: Retrieve API key
      description: |-
        Retrieves an API key by ID.

        **This endpoint is rate limited to 10 QPS.**

        Scopes: `API_KEYS_READ`
      tags:
        - - subpackage_apiKeys
      parameters:
        - name: api_key_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_retrieve-api-key_Response_200'
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    ScopesItems:
      type: string
      enum:
        - value: PAYMENTS_READ
        - value: PAYMENTS_WRITE
        - value: REFUNDS_READ
        - value: REFUNDS_WRITE
        - value: DISPUTES_READ
        - value: DISPUTES_WRITE
        - value: CUSTOMERS_READ
        - value: FEE_PLANS_READ
        - value: GRANTS_READ
        - value: GRANTS_WRITE
        - value: API_KEYS_READ
        - value: API_KEYS_WRITE
        - value: BRANDS_READ
        - value: BRANDS_WRITE
        - value: MERCHANTS_READ
        - value: MERCHANTS_WRITE
        - value: WEBHOOK_CONFIG_READ
        - value: WEBHOOK_CONFIG_WRITE
        - value: WEBHOOK_EVENTS_READ
    Scopes:
      type: array
      items:
        $ref: '#/components/schemas/ScopesItems'
    ApiKey:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique identifier for this API key issued by Cash App. This is the
            API key value that is passed in the `Authorization` header.
        created_at:
          type: string
          format: date-time
          description: >-
            When this API key was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this API key will be automatically deleted and become unusable,
            in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format
            (UTC).
        scopes:
          $ref: '#/components/schemas/Scopes'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this API key, typically used to
            associate the API key with a record in an external system.


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - created_at
        - expires_at
        - scopes
    apiKeys_retrieve-api-key_Response_200:
      type: object
      properties:
        api_key:
          $ref: '#/components/schemas/ApiKey'
      required:
        - api_key

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/api-keys/api_key_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/api-keys/api_key_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/api-keys/api_key_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/api-keys/api_key_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/management/v1/api-keys/api_key_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/management/v1/api-keys/api_key_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/api-keys/api_key_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/api-keys/api_key_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Delete API key

DELETE https://api.cash.app/management/v1/api-keys/{api_key_id}

Deletes an API key. After an API key is deleted, it can no longer be used for authentication. All API clients using the secret associated with this API key  will immediately be forbidden from talking to the Cash App Pay API.

<Note title="Note">
 There is no way to un-delete an API key, so treat this endpoint with caution in production environments.
</Note>

**This endpoint is rate limited to 5 QPS.**

Scopes: `API_KEYS_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/delete-api-key

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete API key
  version: endpoint_apiKeys.delete-api-key
paths:
  /api-keys/{api_key_id}:
    delete:
      operationId: delete-api-key
      summary: Delete API key
      description: >-
        Deletes an API key. After an API key is deleted, it can no longer be
        used for authentication. All API clients using the secret associated
        with this API key  will immediately be forbidden from talking to the
        Cash App Pay API.


        <Note title="Note">
         There is no way to un-delete an API key, so treat this endpoint with caution in production environments.
        </Note>


        **This endpoint is rate limited to 5 QPS.**


        Scopes: `API_KEYS_WRITE`
      tags:
        - - subpackage_apiKeys
      parameters:
        - name: api_key_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiKeys_delete-api-key_Response_200'
components:
  schemas:
    apiKeys_delete-api-key_Response_200:
      type: object
      properties: {}

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/api-keys/api_key_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.delete(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/api-keys/api_key_id';
const options = {
  method: 'DELETE',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/api-keys/api_key_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/api-keys/api_key_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.cash.app/management/v1/api-keys/api_key_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.cash.app/management/v1/api-keys/api_key_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/api-keys/api_key_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/api-keys/api_key_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Api_key

<EndpointSchemaSnippet endpoint="GET /api-key-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "created_at": "2022-01-01T00:00:00Z",
    "expires_at": "2022-02-01T00:00:00Z",
    "scopes": [
      "PAYMENTS_READ"
    ],
    "reference_id": "string"
  }
  ```
</Aside>

---

# Scopes

<EndpointSchemaSnippet endpoint="GET /scopes-schema-test" selector="response.body" />

<Aside>
  ```json Example
  [
    "PAYMENTS_READ"
  ]
  ```
</Aside>

---

# List webhook endpoints

GET https://api.cash.app/management/v1/webhook-endpoints

Returns a list of webhook endpoints matching the query parameters provided.

Scopes: `WEBHOOK_CONFIG_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/list-webhook-endpoints

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List webhook endpoints
  version: endpoint_webhooks.list-webhook-endpoints
paths:
  /webhook-endpoints:
    get:
      operationId: list-webhook-endpoints
      summary: List webhook endpoints
      description: >-
        Returns a list of webhook endpoints matching the query parameters
        provided.


        Scopes: `WEBHOOK_CONFIG_READ`
      tags:
        - - subpackage_webhooks
      parameters:
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of webhook endpoints to return.
          required: false
          schema:
            type: integer
            default: 50
        - name: reference_id
          in: query
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
          required: false
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/webhooks_list-webhook-endpoints_Response_200
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    EventType:
      type: string
      enum:
        - value: customer.created
        - value: customer.deleted
        - value: customer.updated
        - value: customer_request.state.updated
        - value: dispute.created
        - value: dispute.state.updated
        - value: grant.created
        - value: grant.status.updated
        - value: merchant.status.updated
        - value: payment.status.updated
        - value: refund.status.updated
    ApiVersion:
      type: string
      enum:
        - value: v1
    EventConfiguration:
      type: object
      properties:
        event_type:
          $ref: '#/components/schemas/EventType'
        api_version:
          $ref: '#/components/schemas/ApiVersion'
      required:
        - event_type
        - api_version
    WebhookEndpointStatus:
      type: string
      enum:
        - value: APPROVED
        - value: ENDPOINT_URL_UNDER_REVIEW
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          description: The unique ID for a webhook endpoint issued by Cash App.
        api_key_id:
          type: string
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The events are delivered to this endpoint URL. If NULL, events will
            be not be delivered to an endpoint but will still be persisted and
            accessible via the List Webhook Events API.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        created_at:
          type: string
          format: date-time
          description: The timestamp of when this webhook endpoint was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when this endpoint was last updated.
        delivery_timeout:
          type: number
          format: double
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
        status:
          $ref: '#/components/schemas/WebhookEndpointStatus'
      required:
        - id
        - api_key_id
        - url
        - event_configurations
        - created_at
        - updated_at
        - delivery_timeout
        - status
    webhooks_list-webhook-endpoints_Response_200:
      type: object
      properties:
        webhook_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - webhook_endpoints

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/webhook-endpoints"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/webhook-endpoints';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/webhook-endpoints"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/management/v1/webhook-endpoints")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/management/v1/webhook-endpoints', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/webhook-endpoints");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/webhook-endpoints")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Create webhook endpoint

POST https://api.cash.app/management/v1/webhook-endpoints
Content-Type: application/json

Creates a new webhook endpoint which Cash App can send events to.

<Note title="Note">
 Webhook events will not be successfully delivered for new domains until the new domain is allow-listed. New domains must be manually reviewed and allow-listed. It will typically take 1 business day to allow-list new domains.
</Note>

Scopes: `WEBHOOK_CONFIG_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/create-webhook-endpoint

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create webhook endpoint
  version: endpoint_webhooks.create-webhook-endpoint
paths:
  /webhook-endpoints:
    post:
      operationId: create-webhook-endpoint
      summary: Create webhook endpoint
      description: |-
        Creates a new webhook endpoint which Cash App can send events to.

        <Note title="Note">
         Webhook events will not be successfully delivered for new domains until the new domain is allow-listed. New domains must be manually reviewed and allow-listed. It will typically take 1 business day to allow-list new domains.
        </Note>

        Scopes: `WEBHOOK_CONFIG_WRITE`
      tags:
        - - subpackage_webhooks
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/webhooks_create-webhook-endpoint_Response_201
        '400':
          description: Bad Request
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                idempotency_key:
                  $ref: '#/components/schemas/IdempotencyKey'
                webhook_endpoint:
                  $ref: >-
                    #/components/schemas/WebhookEndpointsPostRequestBodyContentApplicationJsonSchemaWebhookEndpoint
              required:
                - idempotency_key
                - webhook_endpoint
components:
  schemas:
    IdempotencyKey:
      type: string
    EventType:
      type: string
      enum:
        - value: customer.created
        - value: customer.deleted
        - value: customer.updated
        - value: customer_request.state.updated
        - value: dispute.created
        - value: dispute.state.updated
        - value: grant.created
        - value: grant.status.updated
        - value: merchant.status.updated
        - value: payment.status.updated
        - value: refund.status.updated
    ApiVersion:
      type: string
      enum:
        - value: v1
    EventConfiguration:
      type: object
      properties:
        event_type:
          $ref: '#/components/schemas/EventType'
        api_version:
          $ref: '#/components/schemas/ApiVersion'
      required:
        - event_type
        - api_version
    WebhookEndpointsPostRequestBodyContentApplicationJsonSchemaWebhookEndpoint:
      type: object
      properties:
        api_key_id:
          type: string
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        url:
          type:
            - string
            - 'null'
          description: >-
            The URL of the endpoint which events will be delivered to. If NULL
            is specified, events will be not be delivered to an endpoint but
            will still be persisted and accessible via the List Webhook Events
            API.
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        delivery_timeout:
          type: number
          format: double
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type: number
          format: double
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
      required:
        - api_key_id
        - event_configurations
        - url
    WebhookEndpointStatus:
      type: string
      enum:
        - value: APPROVED
        - value: ENDPOINT_URL_UNDER_REVIEW
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          description: The unique ID for a webhook endpoint issued by Cash App.
        api_key_id:
          type: string
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The events are delivered to this endpoint URL. If NULL, events will
            be not be delivered to an endpoint but will still be persisted and
            accessible via the List Webhook Events API.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        created_at:
          type: string
          format: date-time
          description: The timestamp of when this webhook endpoint was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when this endpoint was last updated.
        delivery_timeout:
          type: number
          format: double
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
        status:
          $ref: '#/components/schemas/WebhookEndpointStatus'
      required:
        - id
        - api_key_id
        - url
        - event_configurations
        - created_at
        - updated_at
        - delivery_timeout
        - status
    webhooks_create-webhook-endpoint_Response_201:
      type: object
      properties:
        webhook_endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
      required:
        - webhook_endpoint

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/webhook-endpoints"

payload = {
    "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
    "webhook_endpoint": {
        "api_key_id": "KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
        "event_configurations": [
            {
                "event_type": "customer.created",
                "api_version": "v1"
            }
        ],
        "url": "string"
    }
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/webhook-endpoints';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","webhook_endpoint":{"api_key_id":"KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30","event_configurations":[{"event_type":"customer.created","api_version":"v1"}],"url":"string"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/webhook-endpoints"

	payload := strings.NewReader("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"webhook_endpoint\": {\n    \"api_key_id\": \"KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30\",\n    \"event_configurations\": [\n      {\n        \"event_type\": \"customer.created\",\n        \"api_version\": \"v1\"\n      }\n    ],\n    \"url\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"webhook_endpoint\": {\n    \"api_key_id\": \"KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30\",\n    \"event_configurations\": [\n      {\n        \"event_type\": \"customer.created\",\n        \"api_version\": \"v1\"\n      }\n    ],\n    \"url\": \"string\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/webhook-endpoints")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"webhook_endpoint\": {\n    \"api_key_id\": \"KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30\",\n    \"event_configurations\": [\n      {\n        \"event_type\": \"customer.created\",\n        \"api_version\": \"v1\"\n      }\n    ],\n    \"url\": \"string\"\n  }\n}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/webhook-endpoints', [
  'body' => '{
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "webhook_endpoint": {
    "api_key_id": "KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "event_configurations": [
      {
        "event_type": "customer.created",
        "api_version": "v1"
      }
    ],
    "url": "string"
  }
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/webhook-endpoints");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n  \"webhook_endpoint\": {\n    \"api_key_id\": \"KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30\",\n    \"event_configurations\": [\n      {\n        \"event_type\": \"customer.created\",\n        \"api_version\": \"v1\"\n      }\n    ],\n    \"url\": \"string\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
  "webhook_endpoint": [
    "api_key_id": "KEY_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "event_configurations": [
      [
        "event_type": "customer.created",
        "api_version": "v1"
      ]
    ],
    "url": "string"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/webhook-endpoints")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Retrieve webhook endpoint

GET https://api.cash.app/management/v1/webhook-endpoints/{webhook_endpoint_id}

Returns the webhook endpoint matching the `webhook_endpoint_id` provided.

Scopes: `WEBHOOK_CONFIG_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/retrieve-webhook-endpoint

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Retrieve webhook endpoint
  version: endpoint_webhooks.retrieve-webhook-endpoint
paths:
  /webhook-endpoints/{webhook_endpoint_id}:
    get:
      operationId: retrieve-webhook-endpoint
      summary: Retrieve webhook endpoint
      description: >-
        Returns the webhook endpoint matching the `webhook_endpoint_id`
        provided.


        Scopes: `WEBHOOK_CONFIG_READ`
      tags:
        - - subpackage_webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/webhooks_retrieve-webhook-endpoint_Response_200
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    EventType:
      type: string
      enum:
        - value: customer.created
        - value: customer.deleted
        - value: customer.updated
        - value: customer_request.state.updated
        - value: dispute.created
        - value: dispute.state.updated
        - value: grant.created
        - value: grant.status.updated
        - value: merchant.status.updated
        - value: payment.status.updated
        - value: refund.status.updated
    ApiVersion:
      type: string
      enum:
        - value: v1
    EventConfiguration:
      type: object
      properties:
        event_type:
          $ref: '#/components/schemas/EventType'
        api_version:
          $ref: '#/components/schemas/ApiVersion'
      required:
        - event_type
        - api_version
    WebhookEndpointStatus:
      type: string
      enum:
        - value: APPROVED
        - value: ENDPOINT_URL_UNDER_REVIEW
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          description: The unique ID for a webhook endpoint issued by Cash App.
        api_key_id:
          type: string
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The events are delivered to this endpoint URL. If NULL, events will
            be not be delivered to an endpoint but will still be persisted and
            accessible via the List Webhook Events API.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        created_at:
          type: string
          format: date-time
          description: The timestamp of when this webhook endpoint was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when this endpoint was last updated.
        delivery_timeout:
          type: number
          format: double
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
        status:
          $ref: '#/components/schemas/WebhookEndpointStatus'
      required:
        - id
        - api_key_id
        - url
        - event_configurations
        - created_at
        - updated_at
        - delivery_timeout
        - status
    webhooks_retrieve-webhook-endpoint_Response_200:
      type: object
      properties:
        webhook_endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
      required:
        - webhook_endpoint

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Update webhook endpoint

PATCH https://api.cash.app/management/v1/webhook-endpoints/{webhook_endpoint_id}
Content-Type: application/json

Updates the webhook endpoint matching the `webhook_endpoint_id` provided.

Scopes: `WEBHOOK_CONFIG_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/update-webhook-endpoint

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Update webhook endpoint
  version: endpoint_webhooks.update-webhook-endpoint
paths:
  /webhook-endpoints/{webhook_endpoint_id}:
    patch:
      operationId: update-webhook-endpoint
      summary: Update webhook endpoint
      description: >-
        Updates the webhook endpoint matching the `webhook_endpoint_id`
        provided.


        Scopes: `WEBHOOK_CONFIG_WRITE`
      tags:
        - - subpackage_webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/webhooks_update-webhook-endpoint_Response_200
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_endpoint:
                  $ref: >-
                    #/components/schemas/WebhookEndpointsWebhookEndpointIdPatchRequestBodyContentApplicationJsonSchemaWebhookEndpoint
              required:
                - webhook_endpoint
components:
  schemas:
    EventType:
      type: string
      enum:
        - value: customer.created
        - value: customer.deleted
        - value: customer.updated
        - value: customer_request.state.updated
        - value: dispute.created
        - value: dispute.state.updated
        - value: grant.created
        - value: grant.status.updated
        - value: merchant.status.updated
        - value: payment.status.updated
        - value: refund.status.updated
    ApiVersion:
      type: string
      enum:
        - value: v1
    EventConfiguration:
      type: object
      properties:
        event_type:
          $ref: '#/components/schemas/EventType'
        api_version:
          $ref: '#/components/schemas/ApiVersion'
      required:
        - event_type
        - api_version
    WebhookEndpointsWebhookEndpointIdPatchRequestBodyContentApplicationJsonSchemaWebhookEndpoint:
      type: object
      properties:
        url:
          type:
            - string
            - 'null'
          format: uri
          description: The events are delivered to this endpoint URL.
        reference_id:
          type:
            - string
            - 'null'
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        api_key_id:
          type: string
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        delivery_timeout:
          type: number
          format: double
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
    WebhookEndpointStatus:
      type: string
      enum:
        - value: APPROVED
        - value: ENDPOINT_URL_UNDER_REVIEW
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          description: The unique ID for a webhook endpoint issued by Cash App.
        api_key_id:
          type: string
          description: >-
            The API key ID which will be used to sign requests made to this
            webhook endpoint.
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this webhook endpoint, typically used
            to associate the webhook endpoint with a record in an external
            system.
        url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The events are delivered to this endpoint URL. If NULL, events will
            be not be delivered to an endpoint but will still be persisted and
            accessible via the List Webhook Events API.
        event_configurations:
          type: array
          items:
            $ref: '#/components/schemas/EventConfiguration'
          description: >-
            The list of supported event types for this webhook endpoint. Events
            of a particular type will only be sent to endpoints that contain the
            type in this list.
        created_at:
          type: string
          format: date-time
          description: The timestamp of when this webhook endpoint was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when this endpoint was last updated.
        delivery_timeout:
          type: number
          format: double
          default: 5000
          description: >-
            The duration, in milliseconds, that Cash App will take to deliver an
            event to this endpoint before timing out.
        max_delivery_frequency:
          type:
            - number
            - 'null'
          format: double
          description: >-
            The maximum number of events per second that will be delivered to
            this endpoint before rate limiting kicks in. The default for this
            field is unset (NULL) which means no rate limiting. However, if you
            enable rate limiting, the values can range from 1 to 100000.
        status:
          $ref: '#/components/schemas/WebhookEndpointStatus'
      required:
        - id
        - api_key_id
        - url
        - event_configurations
        - created_at
        - updated_at
        - delivery_timeout
        - status
    webhooks_update-webhook-endpoint_Response_200:
      type: object
      properties:
        webhook_endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
      required:
        - webhook_endpoint

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id"

payload = {}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id';
const options = {
  method: 'PATCH',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.patch("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id', [
  'body' => '{}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# Delete webhook endpoint

DELETE https://api.cash.app/management/v1/webhook-endpoints/{webhook_endpoint_id}

Deletes the webhook endpoint matching the `webhook_endpoint_id` provided. Note: Events that are created before the webhook endpoint was deleted will still be delivered after the webhook endpoint gets deleted.

Scopes: `WEBHOOK_CONFIG_WRITE`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/delete-webhook-endpoint

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Delete webhook endpoint
  version: endpoint_webhooks.delete-webhook-endpoint
paths:
  /webhook-endpoints/{webhook_endpoint_id}:
    delete:
      operationId: delete-webhook-endpoint
      summary: Delete webhook endpoint
      description: >-
        Deletes the webhook endpoint matching the `webhook_endpoint_id`
        provided. Note: Events that are created before the webhook endpoint was
        deleted will still be delivered after the webhook endpoint gets deleted.


        Scopes: `WEBHOOK_CONFIG_WRITE`
      tags:
        - - subpackage_webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/webhooks_delete-webhook-endpoint_Response_200
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    webhooks_delete-webhook-endpoint_Response_200:
      type: object
      properties: {}

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.delete(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id';
const options = {
  method: 'DELETE',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id"

	req, _ := http.NewRequest("DELETE", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.delete("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/webhook-endpoints/webhook_endpoint_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# List webhook events

GET https://api.cash.app/management/v1/webhook-events

Returns a list of all webhook events matching the query parameters provided. Expired events are not included.

Scopes: `WEBHOOK_EVENTS_READ`

Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/list-webhook-events

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: List webhook events
  version: endpoint_webhooks.list-webhook-events
paths:
  /webhook-events:
    get:
      operationId: list-webhook-events
      summary: List webhook events
      description: >-
        Returns a list of all webhook events matching the query parameters
        provided. Expired events are not included.


        Scopes: `WEBHOOK_EVENTS_READ`
      tags:
        - - subpackage_webhooks
      parameters:
        - name: webhook_endpoint_id
          in: query
          description: Events delivered to this webhook endpoint ID.
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: >-
            The status of an event that was delivered to a webhook endpoint. The
            status can either be PENDING, SUCCESS, or FAILED.
          required: false
          schema:
            $ref: '#/components/schemas/WebhookEventsGetParametersStatus'
        - name: event_type
          in: query
          description: The type of event that will be sent to the webhook endpoint.
          required: false
          schema:
            $ref: '#/components/schemas/WebhookEventsGetParametersEventType'
        - name: cursor
          in: query
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of results for the
            original query.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of webhook events to return.
          required: false
          schema:
            type: integer
            default: 100
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhooks_list-webhook-events_Response_200'
        '400':
          description: Bad Request
          content: {}
components:
  schemas:
    WebhookEventsGetParametersStatus:
      type: string
      enum:
        - value: PENDING
        - value: SUCCESS
        - value: FAILED
    WebhookEventsGetParametersEventType:
      type: string
      enum:
        - value: customer.created
        - value: customer.deleted
        - value: customer.updated
        - value: customer_request.state.updated
        - value: dispute.created
        - value: dispute.state.updated
        - value: grant.created
        - value: grant.status.updated
        - value: merchant.status.updated
        - value: payment.status.updated
        - value: refund.status.updated
    EventType:
      type: string
      enum:
        - value: customer.created
        - value: customer.deleted
        - value: customer.updated
        - value: customer_request.state.updated
        - value: dispute.created
        - value: dispute.state.updated
        - value: grant.created
        - value: grant.status.updated
        - value: merchant.status.updated
        - value: payment.status.updated
        - value: refund.status.updated
    EventStatus:
      type: string
      enum:
        - value: PENDING
        - value: FAILED
        - value: SUCCESS
    Customer:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this customer, typically used to
            associate the customer with a record in an external system. This
            value can be provided via the
            `CustomerRequest.customer_metadata.reference_id` attribute. Upon
            approval of the CustomerRequest, a corresponding customer resource
            is created with the `reference_id` attribute.
      required:
        - id
        - cashtag
    EventDataDataObject0:
      type: object
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
    Country:
      type: string
      enum:
        - value: US
    Currency:
      type: string
      enum:
        - value: USD
    Category:
      type: string
    MerchantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: RISK_DISABLED
        - value: COMPLIANCE_DISABLED
        - value: CLIENT_DISABLED
        - value: PENDING
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          description: >-
            First line of the street address, typically including street number,
            street name, and / or building name.


            Min length: `1`

            Max length: `1024`
        address_line_2:
          type: string
          description: |-
            Second line of the address, if any.

            Min length: `1`
            Max length: `1024`
        locality:
          type: string
          description: |-
            City or township where the entity is located.

            Min length: `1`
            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        postal_code:
          type: string
          description: |-
            ZIP or postal code.

            Min length: `1`
            Max length: `128`
        administrative_district_level_1:
          type: string
          description: |-
            State or province.

            Min length: `1`
            Max length: `1024`
      required:
        - country
    Metadata:
      type: object
      additionalProperties:
        type: string
    MerchantFeePlans:
      type: object
      properties:
        in_app_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-app payments.
        in_person_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            in-person payments.
        online_fee_plan_id:
          type: string
          description: >-
            The fee plan ID identifying the fee plan that will be used for all
            online payments.
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the merchant issued by Cash App.

            Min length: `1`
            Max length: `128`
        brand_id:
          type: string
          description: |-
            ID of the brand associated with this merchant.

            Min length: `1`
            Max length: `128`
        name:
          type: string
          description: >-
            The name of the individual or business entity associated with the
            merchant.


            Min length: `1`

            Max length: `1024`
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        category:
          $ref: '#/components/schemas/Category'
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this merchant, typically used to
            associate the merchant with a record in an external system.
            Independent from the [brand
            reference_id](https://developers.cash.app/docs/api/network-api/operations/create-a-brand#request-body).


            Min length: `1`

            Max length: `1024`
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: >-
            Whether or not this merchant can be used to accept payments or issue
            refunds.


            - `ACTIVE`: The merchant can accept payments or issue refunds.

            - `RISK_DISABLED`: Cash App Pay blocked this merchant due to them
            being high risk. There is no way to re-enable them programmaticaly.

            - `COMPLIANCE_DISABLED`: Cash App Pay blocked this merchant due to
            them not following the terms of service, Program Rules, or local
            laws. There is no way to re-enable them programmaticaly.

            - `CLIENT_DISABLED`: The client called the
            [UpdateMerchant](Network-API.v1.yaml/paths/~1merchants~1{merchant_id}/patch)
            endpoint and disabled this merchant, preventing it from being able
            to handle payments or refunds. To reverse this, call the endpoint
            again with the status field set to `ACTIVE`.

            - `PENDING`: The merchant is not ready to accept payments or refunds
            yet; the registration process is still running.
        created_at:
          type: string
          format: date-time
          description: >-
            When this merchant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this merchant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        address:
          $ref: '#/components/schemas/Address'
        site_url:
          type: string
          format: uri
          description: |-
            The URL of the website, if this merchant is for an eCommerce site.

            Min length: `8`
            Max length: `8000`
        metadata:
          $ref: '#/components/schemas/Metadata'
        default_fee_plans:
          $ref: '#/components/schemas/MerchantFeePlans'
      required:
        - id
        - brand_id
        - name
        - country
        - currency
        - category
        - reference_id
        - status
        - created_at
        - updated_at
        - address
    EventDataDataObject1:
      type: object
      properties:
        merchant:
          $ref: '#/components/schemas/Merchant'
    DisputeReason:
      type: string
      enum:
        - value: FR10
        - value: FR11
        - value: PE10
        - value: PE11
        - value: PE12
        - value: CD10
        - value: CD11
        - value: CD13
    DisputeSettlementWithholding:
      type: string
      enum:
        - value: NOT_WITHHELD
        - value: WITHHELD_ALREADY
    DisputeState:
      type: string
      enum:
        - value: RESPONSE_REQUIRED
        - value: NO_RESPONSE_REQUIRED
        - value: PROCESSING
        - value: ACCEPTED
        - value: WON
        - value: PARTIALLY_WON
        - value: LOST
    Dispute:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the dispute issued by Cash App.

            Min length: `1`
            Max length: `128`
        payment_id:
          type: string
          description: |-
            ID of the disputed payment.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of disputed money, in the lowest denomination of currency on
            the associated payment.


            Min value: `1`
        customer_credited_amount:
          type:
            - integer
            - 'null'
          description: >-
            The amount credited to the Customer after resolving the dispute. 


            Note: The amount will be in the lowest denomination of the currency
            used on the associated payment.


            Min value: `0`
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: >-
            4-digit code consisting of 2 letters followed by 2 numbers that
            indicates why the dispute was created, at a high level.


            Current values:


            - `FR10`: Customer has no knowledge of the payment.

            - `FR11`: Customer has no knowledge of the payment and liability has
            shifted to the merchant due to collusion, fraud monitoring program
            thresholds, or any other reason.

            - `PE10`: Payment was processed twice.

            - `PE11`: Payment amount differs from agreed amount.

            - `PE12`: Payment was paid for by another means.

            - `CD10`: Cancelled services.

            - `CD11`: Goods or services differ from what was agreed upon for the
            payment.

            - `CD12`: The goods or services were not received.

            - `CD13`: The purchase was cancelled or returned, but the refund has
            not been processed.
        settlement_withholding:
          $ref: '#/components/schemas/DisputeSettlementWithholding'
          description: >-
            Indicates if the disputed amount has already been withheld from a
            settlement or not.


            Current values:


            - `NOT_WITHHELD`: The disputed amount has not yet been withheld in a
            settlement. It may impact future settlements if the dispute is
            "lost" by the merchant.


            - `WITHHELD_ALREADY`: The disputed amount was withheld in a prior
            settlement. This dispute will not impact future settlements.
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The step in the dispute lifecycle that this dispute is currently at:

            - `RESPONSE_REQUIRED`
            - `NO_RESPONSE_REQUIRED`
            - `PROCESSING`
            - `ACCEPTED`
            - `WON`
            - `PARTIALLY_WON`
            - `LOST`
        created_at:
          type: string
          format: date-time
          description: >-
            When this dispute was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        response_due_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the dispute must be challenged by, after which it will be
            automatically accepted, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this dispute was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        merchant_id:
          type: string
          description: |-
            ID of the merchant that collected the disputed payment.

            Min length: `1`
            Max length: `128`
      required:
        - id
        - payment_id
        - amount
        - reason
        - settlement_withholding
        - state
        - created_at
        - updated_at
        - merchant_id
    EventDataDataObject2:
      type: object
      properties:
        dispute:
          $ref: '#/components/schemas/Dispute'
    PaymentStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    PaymentEnrichmentsInitiationActor:
      type: string
      enum:
        - value: CUSTOMER
        - value: MERCHANT
    PaymentEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiationActor'
          description: |-
            The party who initiated the payment.

            - `CUSTOMER`
            - `MERCHANT`
      required:
        - actor
    PaymentEnrichmentsRestrictedCategoriesItems:
      type: string
      enum:
        - value: ALCOHOL
        - value: FINANCIAL_SERVICES
    PaymentEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/PaymentEnrichmentsInitiation'
          description: If present, provides information about transaction initiation.
        recurring_series_id:
          type: string
          description: >-
            If present, indicates that this payment is part of a recurring
            series of payments, such as a subscription.


            The value should contain a unique identifier for the recurring
            series that is constant across all of its payments, so it can be
            used to group them together.


            Min length: `1`

            Max length: `1024`
        statement_descriptor:
          type: string
          description: >-
            If present, adds the descriptor as line item on to a customer's
            payment receipt in their in-app Activity page.

            The descriptor will be present under the header "On statement as".


            Statement descriptor requirements vary by platform. If the input for
            this field exceeds the character limit, it will be truncated to the
            limit, then suffixed with an ellipsis (...).


            Min length: `1`

            Max length: `22`
        restricted_categories:
          type: array
          items:
            $ref: '#/components/schemas/PaymentEnrichmentsRestrictedCategoriesItems'
          description: >-
            If present, indicates that this payment is associated with one or
            more restricted categories. Contact the Cash App Pay support team to
            use this field.
    ErrorCategory:
      type: string
      enum:
        - value: API_ERROR
        - value: AUTHENTICATION_ERROR
        - value: BRAND_ERROR
        - value: DISPUTE_ERROR
        - value: MERCHANT_ERROR
        - value: INVALID_REQUEST_ERROR
        - value: PAYMENT_PROCESSING_ERROR
        - value: RATE_LIMIT_ERROR
        - value: WEBHOOK_ERROR
        - value: API_KEY_ERROR
        - value: GRANT_ERROR
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            See the Error Code Reference for more information.


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
    FeeRate:
      type: object
      properties:
        basis_points:
          type: integer
          description: >-
            The variable fee charged for processing the payment expressed as
            1/100th of a percentage.
        fixed_amount:
          type: integer
          description: >-
            The amount charged for processing the payment, in the lowest
            denomination of currency on the payment.
             **Note: The currency for the fee is found on the fee plan.**
    AuthorizationStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: DECLINED
    Authorization:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this authorization issued by Cash App.

            Min length: 1 character
            Max length: 128 characters
        amount:
          type: integer
          description: >-
            Total authorized amount after this authorization was processed, in
            the lowest denomination of currency on the payment.
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/AuthorizationStatus'
          description: >-
            The step of the authorization processing lifecycle that this
            authorization is currently at.


            Allowed values:

            - AUTHORIZED

            - DECLINED
        created_at:
          type: string
          format: date-time
          description: When this authorization was created, in RFC 3339 format (UTC).
        payment_id:
          type: string
          description: ID of the payment associated with this authorization
        previous_amount:
          type: integer
          description: Total authorized amount before this authorization was requested
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this authorization, typically used to
            associate the authorization with a record in an external system.


            Min length: 1

            Max length: 1024
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the authorization was declined, it contains a list of the reasons
            why it was declined.


            Min number of items: 1
      required:
        - id
        - amount
        - currency
        - status
        - created_at
        - payment_id
        - previous_amount
    Payment:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this payment issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            The amount of money to collect, in the lowest denomination of
            currency on the payment. This is the _original_ amount authorized
            when the payment was created.


            Min value: `1`
        net_amount:
          type: integer
          description: >-
            The amount remaining after refunds and voided payments are deducted
            from the amount field. The amount will be in the lowest denomination
            of the currency on the payment.

            This is the amount that will be shown to the customer in their Cash
            App account.



            Min value: `0`
        captured_amount:
          type: integer
          description: >-
            The amount of money on this payment that has been allocated for
            settlement. The amount will be in the lowest denomination of the
            currency on the payment.


            Min value: `0`
        voided_amount:
          type: integer
          description: >-
            The amount of money on this payment that is no longer authorized and
            has been released back to the customer. The amount will be in the
            lowest denomination of the currency on the payment.


            Min value: `0`
        refunded_amount:
          type: integer
          description: >-
            Sum of captured refunds in the lowest denomination of currency on
            the payment.


            Min value: `0`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that sent this payment.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that received this payment.

            Min length: `1`
            Max length: `128`
        grant_id:
          type: string
          description: |-
            ID of the grant to used to create this payment.

            Min length: `1`
            Max length: `256`
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: >-
            The step of the payment processing lifecycle that this payment is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this payment was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this payment was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        capture_before:
          type: string
          format: date-time
          description: >-
            When this payment should be captured by, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        refund_ids:
          type: array
          items:
            type: string
          description: >-
            A list of one or more IDs associated with refunds issued for this
            payment.


            Min array length: `1`

            Min length of IDs: `1`

            Max length of IDs: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this payment, typically used to
            associate the payment with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        enrichments:
          $ref: '#/components/schemas/PaymentEnrichments'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the payment was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
        fee_amount:
          type: number
          format: double
          description: >-
            The total fee amount that was charged to the merchant for processing
            this payment.
        fee_rate:
          $ref: '#/components/schemas/FeeRate'
          description: >-
            The breakdown of the fee that was charged to the merchant for
            processing this payment.
        authorization_updates:
          type: array
          items:
            $ref: '#/components/schemas/Authorization'
          description: >-
            A list of authorization update attempts associated with this
            payment, sorted in chronological order.


            Note: This field contains only the authorization update attempts, so
            this field will be empty when 

            the payment is first created (even though the amount is authorized
            in this flow, it is not an update).
      required:
        - id
        - amount
        - net_amount
        - captured_amount
        - voided_amount
        - refunded_amount
        - currency
        - customer_id
        - merchant_id
        - grant_id
        - status
        - created_at
        - updated_at
    EventDataDataObject3:
      type: object
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
    OneTimePaymentActionType:
      type: string
      enum:
        - value: ONE_TIME_PAYMENT
    OneTimePaymentAction:
      type: object
      properties:
        amount:
          type: integer
          description: >-
            Amount to charge the customer, in the lowest unit of the associated
            currency.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        scope_id:
          type: string
          description: >-
            ID of the client, brand, or merchant that will charge the customer.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            If a merchant ID is passed, the grant from this action can be used
            to create a payment for the merchant with a matching ID.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OneTimePaymentActionType'
          description: The type of the action (`ONE_TIME_PAYMENT`).
      required:
        - scope_id
        - type
    OnFilePaymentActionType:
      type: string
      enum:
        - value: ON_FILE_PAYMENT
      default: ON_FILE_PAYMENT
    OnFilePaymentAction:
      type: object
      properties:
        scope_id:
          type: string
          description: >-
            ID of the client or brand that will charge customers.


            If a client ID is passed, the grant from this action can be used to
            create a payment for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a payment for any merchant that has a matching brand ID.


            Merchant IDs may *not* be passed.


            Min length: `1`

            Max length: `128`
        type:
          $ref: '#/components/schemas/OnFilePaymentActionType'
          description: The type of the action (`ON_FILE_PAYMENT`).
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - scope_id
        - type
    OnFileDepositActionType:
      type: string
      enum:
        - value: ON_FILE_DEPOSIT
    OnFileDepositAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/OnFileDepositActionType'
          description: The type of the action (`ON_FILE_DEPOSIT`).
        scope_id:
          type: string
          description: >-
            ID of the client or brand that indicates the set of merchants that
            will deposit to customers.


            If a client ID is passed, the grant from this action can be used to
            create a deposit for any merchant owned by the client.


            If a brand ID is passed, the grant from this action can be used to
            create a deposit for any merchant that has a matching brand ID.

            Min length: `1`

            Max length: `128`
        account_reference_id:
          type: string
          description: >-
            Identifier of the account or customer associated to the on file
            action.
      required:
        - type
        - scope_id
        - account_reference_id
    LinkAccountActionType:
      type: string
      enum:
        - value: LINK_ACCOUNT
    LinkAccountAction:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkAccountActionType'
          description: The type of the action (`LINK_ACCOUNT`).
      required:
        - type
    Action:
      oneOf:
        - $ref: '#/components/schemas/OneTimePaymentAction'
        - $ref: '#/components/schemas/OnFilePaymentAction'
        - $ref: '#/components/schemas/OnFileDepositAction'
        - $ref: '#/components/schemas/LinkAccountAction'
    GrantStatus:
      type: string
      enum:
        - value: ACTIVE
        - value: CONSUMED
        - value: REVOKED
        - value: EXPIRED
    GrantType:
      type: string
      enum:
        - value: ONE_TIME
        - value: EXTENDED
    Channel:
      type: string
      enum:
        - value: IN_PERSON
        - value: ONLINE
        - value: IN_APP
    Grant:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this grant issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          description: |-
            ID of the customer that approved this grant.

            Min length: `1`
            Max length: `128`
        request_id:
          type: string
          description: >-
            A unique identifier issued by Cash App for the customer request that
            resulted in the creation of this grant.


            Min length: `1`

            Max length: `128`
        action:
          $ref: '#/components/schemas/Action'
        status:
          $ref: '#/components/schemas/GrantStatus'
          description: >-
            Describes whether or not this grant can be used to perform the
            action associated with it.


            If `ACTIVE`, it can be used to perform the action.


            If `EXPIRED`, it may no longer be used to perform the action due to
            the current time being past the "expires_at" time.


            If `CONSUMED`, it was already redeemed to perform the action and
            cannot be used again.


            If `REVOKED`, the customer or merchant explicitly unauthorized the
            grant, preventing it from being used to perform the action.
        type:
          $ref: '#/components/schemas/GrantType'
          description: >-
            Describes whether this grant can be only be used once (`ONE_TIME`)
            or repeatedly (`EXTENDED`).
        channel:
          $ref: '#/components/schemas/Channel'
        created_at:
          type: string
          format: date-time
          description: >-
            When this grant was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this grant was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            If present, indicates when the grant's status will become `EXPIRED`,
            preventing a client from using it to create payments or refunds.


            The timestamp is in the [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - request_id
        - action
        - status
        - type
        - channel
        - created_at
        - updated_at
    EventDataDataObject4:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/Grant'
    RefundStatus:
      type: string
      enum:
        - value: AUTHORIZED
        - value: CAPTURED
        - value: VOIDED
        - value: DECLINED
    Refund:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this refund issued by Cash App.

            Min length: `1`
            Max length: `128`
        amount:
          type: integer
          description: >-
            Amount of money to refund, in the lowest denomination of currency on
            the refund.


            Min value: `1`
        currency:
          $ref: '#/components/schemas/Currency'
        customer_id:
          type: string
          description: |-
            ID of the customer that received this refund.

            Min length: `1`
            Max length: `128`
        merchant_id:
          type: string
          description: |-
            ID of the merchant that issued this refund.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: >-
            The step of the refund processing lifecycle that this refund is
            currently at.


            - `AUTHORIZED`

            - `CAPTURED`

            - `VOIDED`

            - `DECLINED`
        created_at:
          type: string
          format: date-time
          description: >-
            When this refund was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this refund was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        grant_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `256`
        payment_id:
          type: string
          description: |-
            This is currently unused and empty.

            Min length: `1`
            Max length: `128`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this refund, typically used to
            associate the refund with a record in an external system.


            Min length: `1`

            Max length: `1024`
        metadata:
          $ref: '#/components/schemas/Metadata'
        decline_errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            If the refund was declined, contains a list of the reasons why it
            was declined.


            Min number of items: `1`
      required:
        - id
        - amount
        - currency
        - customer_id
        - merchant_id
        - status
        - created_at
        - updated_at
    EventDataDataObject5:
      type: object
      properties:
        refund:
          $ref: '#/components/schemas/Refund'
    RequestStatus:
      type: string
      enum:
        - value: APPROVED
        - value: DECLINED
        - value: PENDING
        - value: PROCESSING
      default: PENDING
    RequestAuthFlowTriggers:
      type: object
      properties:
        qr_code_image_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as a PNG file.


            Min length: `8`

            Max length: `1024`
        qr_code_svg_url:
          type: string
          format: uri
          description: >-
            Link to a QR code customers can scan with Cash App to authorize the
            given action, encoded as an SVG file.


            Min length: `8`

            Max length: `1024`
        mobile_url:
          type: string
          format: uri
          description: >-
            If on an Android or iOS device, the URL to redirect customers to in
            order to authorize the given action.


            Min length: `8`

            Max length: `1024`
        refreshes_at:
          type: string
          format: date-time
          description: >-
            When the QR code image URL will be rotated. Generally, it will
            rotate every ~20 seconds and become invalid after 30 seconds.
        desktop_url:
          type: string
          format: uri
          description: >-
            If on a desktop browser, the URL to redirect customers to in order
            to authorize the given action.


            Min length: `8`

            Max length: `1024`
      required:
        - qr_code_image_url
        - qr_code_svg_url
        - mobile_url
        - refreshes_at
    RequestOriginType:
      type: string
      enum:
        - value: DIRECT
        - value: REQUEST_INITIATOR
    RequestOrigin:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/RequestOriginType'
          description: >-
            The method used to create the customer request.


            - `DIRECT` - the client or SDKs created this customer request by
            calling the "CreateCustomerRequest" endpoint

            - `REQUEST_INITIATOR` - a customer interacted with a request
            initiator and caused Cash App to create a customer request.
        id:
          type: string
          description: |-
            If present, is the ID of the initiator used to create this request.

            Min length: `1`
            Max length: `128`
      required:
        - type
    RequestRequesterProfile:
      type: object
      properties:
        name:
          type: string
          description: |-
            Name of the brand to be shown in Cash App next to payments.

            Min length: `1`
            Max length: `1024`
        logo_url:
          type: string
          format: uri
          description: >-
            URL to the image of the entity (brand or client) that is requesting
            permission to perform the actions on the customer request.


            Formats:

            - `.jpg`

            - `.jpeg`

            - `.png`


            Min length: `8`

            Max length: `8000`
      required:
        - name
        - logo_url
    RequestCustomerProfile:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this customer issued by Cash App.

            Min length: `1`
            Max length: `128`
        cashtag:
          type: string
          description: >-
            Public identifier for the customer on Cash App. [Learn
            more](https://cash.app/help/us/en-us/3123-cashtags).


            Min length: `1`

            Max length: `1024`
      required:
        - id
        - cashtag
    CustomerMetadata:
      type: object
      properties:
        reference_id:
          type: string
          description: >-
            The `reference_id` of the customer approving this request. When a
            customer approves this request, that customer will be associated
            with this `reference_id`.
    Request:
      type: object
      properties:
        id:
          type: string
          description: |-
            A unique identifier for the request issued by Cash App.

            Min length: `1`
            Max length: `128`
        status:
          $ref: '#/components/schemas/RequestStatus'
          description: >-
            Indicates if the state is approved, declined, or pending. Approved
            requests have grants, while pending and declined grants do not.


            Current values:


            - `PENDING`: The request has been created, but not responded to.

            - `PROCESSING`: The Cash App customer is actively responding to the
            request on their mobile device, and will require time to fill out
            information before the request is approved / declined.

            - `APPROVED`: The request was approved by the customer and grants
            have been created for the provided actions.

            - `DECLINED`: The request was denied by the customer. No grants were
            created.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            Represents what the client intends to do to a customer if given
            authorization.


            No duplicate action types allowed.


            Min number of items: `1`

            Max number of items: `5`
        auth_flow_triggers:
          $ref: '#/components/schemas/RequestAuthFlowTriggers'
          description: >-
            While the request is `PENDING`, contains different methods that can
            be used to start

            the authorization flow in the Cash App mobile application. Its
            contents refresh each time

            the `refreshes_at` timestamp passes. When the

            data refreshes, you should update any buttons

            or QR codes referring to it immediately.


            After a request has been scanned (and is no

            longer in the `PENDING` status), this

            field will no longer be returned.
        redirect_url:
          type: string
          format: uri
          description: >-
            If this request is responded to via mobile redirect, this field
            specifies the URL that Cash App will open for a customer in the
            mobile device's default browser after the request is approved or
            declined.
        created_at:
          type: string
          format: date-time
          description: >-
            When this customer request was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When the customer request was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        expires_at:
          type: string
          format: date-time
          description: >-
            When this customer request will be automatically declined by Cash
            App, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)
            format (UTC).
        origin:
          $ref: '#/components/schemas/RequestOrigin'
          description: Metadata describing how the customer request was created.
        channel:
          $ref: '#/components/schemas/Channel'
        grants:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
          description: >-
            If present, contains grants that can be used to perform actions
            specified in the request using the Network API.


            Each grant corresponds directly to an action on the request.


            Min number of items: `1`

            Max number of items: `5`
        reference_id:
          type: string
          description: >-
            A user-defined identifier for this request, typically used to
            associate the resource with a record in an external system.


            Min length: `1`

            Max length: `1024`
        requester_profile:
          $ref: '#/components/schemas/RequestRequesterProfile'
          description: >-
            Details about the brand or client that are requesting permission to
            perform the actions on the customer request.
        customer_profile:
          $ref: '#/components/schemas/RequestCustomerProfile'
          description: >-
            If the customer request was approved, contains the identity of the
            Cash App customer that approved it.
        metadata:
          $ref: '#/components/schemas/Metadata'
        customer_metadata:
          $ref: '#/components/schemas/CustomerMetadata'
      required:
        - id
        - status
        - actions
        - redirect_url
        - created_at
        - updated_at
        - expires_at
        - origin
        - channel
    EventDataDataObject6:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/Request'
    EventDataDataObject:
      oneOf:
        - $ref: '#/components/schemas/EventDataDataObject0'
        - $ref: '#/components/schemas/EventDataDataObject1'
        - $ref: '#/components/schemas/EventDataDataObject2'
        - $ref: '#/components/schemas/EventDataDataObject3'
        - $ref: '#/components/schemas/EventDataDataObject4'
        - $ref: '#/components/schemas/EventDataDataObject5'
        - $ref: '#/components/schemas/EventDataDataObject6'
    EventDataType:
      type: string
      enum:
        - value: customer
        - value: merchant
        - value: dispute
        - value: grant
        - value: payment
        - value: refund
        - value: request
    EventDataData:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique ID provided by Cash App for the resource contained in the
            event.
        object:
          $ref: '#/components/schemas/EventDataDataObject'
          description: The snapshot of the resource contained in the event.
        type:
          $ref: '#/components/schemas/EventDataType'
      required:
        - id
        - object
        - type
    EventData:
      type: object
      properties:
        event_id:
          type: string
          description: The unique ID of the webhook event.
        type:
          $ref: '#/components/schemas/EventType'
        created_at:
          type: string
          format: date-time
          description: The timestamp of when the event was created.
        data:
          $ref: '#/components/schemas/EventDataData'
          description: The underlying data encapsulated in the event.
      required:
        - event_id
        - type
        - created_at
        - data
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for a webhook event issued by Cash App.
        webhook_endpoint_id:
          type: string
          description: This event is delivered to this webhook endpoint ID.
        event_type:
          $ref: '#/components/schemas/EventType'
        status:
          $ref: '#/components/schemas/EventStatus'
        created_at:
          type: string
          format: date-time
          description: The timestamp of when the event was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp of when the event was last updated.
        expires_at:
          type: string
          format: date-time
          description: >-
            The timestamp of when this event will expire and no longer be
            available in Cash App.
        event_data:
          $ref: '#/components/schemas/EventData'
        api_version:
          type: string
          description: The API version used to serialize the event data.
      required:
        - id
        - webhook_endpoint_id
        - event_type
        - status
        - created_at
        - updated_at
        - expires_at
        - event_data
        - api_version
    webhooks_list-webhook-events_Response_200:
      type: object
      properties:
        webhook_events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEvent'
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.
      required:
        - webhook_events

```

## SDK Code Examples

```python
import requests

url = "https://api.cash.app/management/v1/webhook-events"

headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.cash.app/management/v1/webhook-events';
const options = {
  method: 'GET',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/webhook-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/webhook-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'

response = http.request(request)
puts response.read_body
```

```java
HttpResponse<String> response = Unirest.get("https://api.cash.app/management/v1/webhook-events")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .asString();
```

```php
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.cash.app/management/v1/webhook-events', [
  'headers' => [
    'Accept' => 'Accept',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp
var client = new RestClient("https://api.cash.app/management/v1/webhook-events");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/webhook-events")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# WebhookEndpoint

<EndpointSchemaSnippet endpoint="POST /webhook-endpoints" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "WC_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "api_key_id": "string",
    "reference_id": "string",
    "url": "http://example.com",
    "event_configurations": [
      {
        "event_type": "customer.created",
        "api_version": "v1"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "delivery_timeout": 5000,
    "max_delivery_frequency": null,
    "status": "APPROVED"
  }
  ```
</Aside>

---

# WebhookEndpointStatus

<EndpointSchemaSnippet endpoint="GET /webhook-endpoint-status-schema-test" selector="response.body" />

<Aside>
  ```json Example
  APPROVED
  ```
</Aside>

---

# EventConfiguration

<EndpointSchemaSnippet endpoint="GET /event-configuration-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "event_type": "customer.created",
    "api_version": "v1"
  }
  ```
</Aside>

---

# ApiVersion

<EndpointSchemaSnippet endpoint="GET /api-version-schema-test" selector="response.body" />

<Aside>
  ```json Example
  v1
  ```
</Aside>

---

# WebhookEvent

<EndpointSchemaSnippet endpoint="GET /webhook-event-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "id": "WE_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "webhook_endpoint_id": "WC_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "event_type": "customer.created",
    "status": "PENDING",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z",
    "event_data": {
      "event_id": "WE_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
      "type": "customer.created",
      "created_at": "2019-08-24T14:15:22Z",
      "data": {
        "id": "string",
        "object": {
          "customer": {}
        },
        "type": "customer"
      }
    },
    "api_version": "string"
  }
  ```
</Aside>

---

# EventType

<EndpointSchemaSnippet endpoint="GET /event-type-schema-test" selector="response.body" />

<Aside>
  ```json Example
  customer.created
  ```
</Aside>

---

# EventStatus

<EndpointSchemaSnippet endpoint="GET /event-status-schema-test" selector="response.body" />

<Aside>
  ```json Example
  PENDING
  ```
</Aside>

---

# EventData

<EndpointSchemaSnippet endpoint="GET /event-data-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "event_id": "WE_2f6cd0d5cc26b34ac8785026b149797ecc0758be3dc3a857d405f2f62074ef30",
    "type": "customer.created",
    "created_at": "2019-08-24T14:15:22Z",
    "data": {
      "id": "string",
      "object": {
        "customer": {
          "id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
          "cashtag": "string",
          "reference_id": "CUST_123"
        }
      },
      "type": "customer"
    }
  }
  ```
</Aside>

---

# EventDataType

<EndpointSchemaSnippet endpoint="GET /event-data-type-schema-test" selector="response.body" />

<Aside>
  ```json Example
  customer
  ```
</Aside>

---

# Create request chain

POST https://api.cash.app/management/v1/request-chains
Content-Type: application/json

Executes multiple requests, grouped into "chains", in a single call. The API Client (Client) can use multiple chains and specify sub-requests within each chain to run sequentially or in parallel. However the chains, themselves, will only run sequentially.

### Accessing a previous response's value

Clients can access a previous response's value by using the format: `$[previous request's uid]:[key path]`. Clients can use this in the value fields of:
- `requests[].body`
- `requests[].path_params`
- `requests[].query_params`

The request's path `requests[].path` has an extra step to access a previous response's value. In the request's path, the Client will first refer to a key in the `requests[].path_params` field using the format: `{[path_params key name]}`. From there `requests[].path_params` can use the pattern described in **Accessing a previous response's value** to obtain a previous response's value.

<Warning>
The initial security headers will be passed to all requests.

Scopes are not required for this endpoint. However, the API key must contain the appropriate scopes required by the individual requests to execute.
</Warning>

For FAQs and performance improvement details, visit [Optimizing Performance with Request Chaining](../docs/partner-onboarding/optimizing-performance-with-request-chaining.md).


Reference: https://developers.cash.app/cash-app-pay-partner-api/api-reference/management-api/create-request-chain

## OpenAPI Specification

```yaml
openapi: 3.1.1
info:
  title: Create request chain
  version: endpoint_requestChains.create-request-chain
paths:
  /request-chains:
    post:
      operationId: create-request-chain
      summary: Create request chain
      description: >
        Executes multiple requests, grouped into "chains", in a single call. The
        API Client (Client) can use multiple chains and specify sub-requests
        within each chain to run sequentially or in parallel. However the
        chains, themselves, will only run sequentially.


        ### Accessing a previous response's value


        Clients can access a previous response's value by using the format:
        `$[previous request's uid]:[key path]`. Clients can use this in the
        value fields of:

        - `requests[].body`

        - `requests[].path_params`

        - `requests[].query_params`


        The request's path `requests[].path` has an extra step to access a
        previous response's value. In the request's path, the Client will first
        refer to a key in the `requests[].path_params` field using the format:
        `{[path_params key name]}`. From there `requests[].path_params` can use
        the pattern described in **Accessing a previous response's value** to
        obtain a previous response's value.


        <Warning>

        The initial security headers will be passed to all requests.


        Scopes are not required for this endpoint. However, the API key must
        contain the appropriate scopes required by the individual requests to
        execute.

        </Warning>


        For FAQs and performance improvement details, visit [Optimizing
        Performance with Request
        Chaining](../docs/partner-onboarding/optimizing-performance-with-request-chaining.md).
      tags:
        - - subpackage_requestChains
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
        - name: X-Region
          in: header
          required: true
          schema:
            type: string
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/requestChains_create-request-chain_Response_201
        '400':
          description: Bad Request
          content: {}
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              properties:
                requests:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItems
                  description: Requests to execute
                chains:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaChainsItems
                  description: Chains control the order and execution modes of requests
              required:
                - requests
                - chains
components:
  schemas:
    RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PATCH
        - value: PUT
        - value: DELETE
    RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsPathParams:
      type: object
      properties: {}
    RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsQueryParams:
      type: object
      properties: {}
    RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsBody:
      type: object
      properties: {}
    RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItems:
      type: object
      properties:
        uid:
          type: string
          description: Unique identifier for the request
        method:
          $ref: >-
            #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsMethod
          description: HTTP method of the request
        path:
          type: string
          description: >-
            URL path to call. Use format `{path_params key name}` to add
            variable path parameters.
        path_params:
          $ref: >-
            #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsPathParams
          description: >-
            A map of path parameters. The keys represent variables from the
            `path`. The value fields allow for **Accessing a previous response's
            value**.
        query_params:
          $ref: >-
            #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsQueryParams
          description: >-
            A map of query parameters. The value fields allow for **Accessing a
            previous response's value**.
        body:
          $ref: >-
            #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaRequestsItemsBody
          description: >-
            The body that is required for the requested endpoint. The value
            fields allow for **Accessing a previous response's value**.
      required:
        - uid
        - method
        - path
    RequestChainsPostRequestBodyContentApplicationJsonSchemaChainsItemsRequestsItems:
      type: object
      properties:
        uid:
          type: string
          description: Unique identifier for the request to execute
      required:
        - uid
    RequestChainsPostRequestBodyContentApplicationJsonSchemaChainsItemsExecutionMode:
      type: string
      enum:
        - value: SEQUENTIAL
        - value: PARALLEL
    RequestChainsPostRequestBodyContentApplicationJsonSchemaChainsItems:
      type: object
      properties:
        requests:
          type: array
          items:
            $ref: >-
              #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaChainsItemsRequestsItems
        execution_mode:
          $ref: >-
            #/components/schemas/RequestChainsPostRequestBodyContentApplicationJsonSchemaChainsItemsExecutionMode
          description: Execution mode of the requests in a chain
      required:
        - requests
        - execution_mode
    ResponseExecutionStatus:
      type: string
      enum:
        - value: EXECUTED
        - value: NOT_STARTED
    ResponseMethod:
      type: string
      enum:
        - value: GET
        - value: POST
        - value: PATCH
        - value: PUT
        - value: DELETE
    ResponseBody:
      type: object
      properties: {}
    Response:
      type: object
      properties:
        request_uid:
          type: string
          description: Unique identifier for the request
        execution_status:
          $ref: '#/components/schemas/ResponseExecutionStatus'
          description: Execution status of the request
        path:
          type: string
          description: URL path that was called
        method:
          $ref: '#/components/schemas/ResponseMethod'
          description: HTTP method of the request
        status_code:
          type: integer
          description: Status code of the request
        body:
          $ref: '#/components/schemas/ResponseBody'
          description: Response body of the requested endpoint
        completed_at:
          type: string
          format: date-time
          description: >-
            When the request was completed, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - request_uid
        - execution_status
        - path
        - method
    requestChains_create-request-chain_Response_201:
      type: object
      properties:
        responses:
          type: array
          items:
            $ref: '#/components/schemas/Response'
      required:
        - responses

```

## SDK Code Examples

```python Create brand -> create merchant -> retrieve brand -> list brands
import requests

url = "https://api.cash.app/management/v1/request-chains"

payload = {
    "requests": [
        {
            "uid": "request_1",
            "method": "POST",
            "path": "/network/v1/brands",
            "body": {
                "idempotency_key": "idempotency_key",
                "brand": {
                    "name": "Brand Name",
                    "reference_id": "reference_id"
                }
            }
        },
        {
            "uid": "request_2",
            "method": "POST",
            "path": "/network/v1/merchants",
            "body": {
                "idempotency_key": "idempotency_key",
                "merchant": {
                    "name": "Merchant Name",
                    "brand_id": "$request_1:brand.id",
                    "country": "US",
                    "currency": "USD",
                    "category": "5432",
                    "reference_id": "reference_id",
                    "address": { "country": "US" }
                }
            }
        },
        {
            "uid": "request_3",
            "method": "GET",
            "path": "/network/v1/brands/{brandId}",
            "path_params": { "brandId": "$request_1:brand.id" }
        },
        {
            "uid": "request_4",
            "method": "GET",
            "path": "/network/v1/brands",
            "query_params": { "limit": "1" }
        }
    ],
    "chains": [
        {
            "requests": [{ "uid": "request_1" }, { "uid": "request_2" }, { "uid": "request_3" }, { "uid": "request_4" }],
            "execution_mode": "SEQUENTIAL"
        }
    ]
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create brand -> create merchant -> retrieve brand -> list brands
const url = 'https://api.cash.app/management/v1/request-chains';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"requests":[{"uid":"request_1","method":"POST","path":"/network/v1/brands","body":{"idempotency_key":"idempotency_key","brand":{"name":"Brand Name","reference_id":"reference_id"}}},{"uid":"request_2","method":"POST","path":"/network/v1/merchants","body":{"idempotency_key":"idempotency_key","merchant":{"name":"Merchant Name","brand_id":"$request_1:brand.id","country":"US","currency":"USD","category":"5432","reference_id":"reference_id","address":{"country":"US"}}}},{"uid":"request_3","method":"GET","path":"/network/v1/brands/{brandId}","path_params":{"brandId":"$request_1:brand.id"}},{"uid":"request_4","method":"GET","path":"/network/v1/brands","query_params":{"limit":"1"}}],"chains":[{"requests":[{"uid":"request_1"},{"uid":"request_2"},{"uid":"request_3"},{"uid":"request_4"}],"execution_mode":"SEQUENTIAL"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create brand -> create merchant -> retrieve brand -> list brands
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/request-chains"

	payload := strings.NewReader("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands/{brandId}\",\n      \"path_params\": {\n        \"brandId\": \"$request_1:brand.id\"\n      }\n    },\n    {\n      \"uid\": \"request_4\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands\",\n      \"query_params\": {\n        \"limit\": \"1\"\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        },\n        {\n          \"uid\": \"request_4\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create brand -> create merchant -> retrieve brand -> list brands
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/request-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands/{brandId}\",\n      \"path_params\": {\n        \"brandId\": \"$request_1:brand.id\"\n      }\n    },\n    {\n      \"uid\": \"request_4\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands\",\n      \"query_params\": {\n        \"limit\": \"1\"\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        },\n        {\n          \"uid\": \"request_4\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Create brand -> create merchant -> retrieve brand -> list brands
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/request-chains")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands/{brandId}\",\n      \"path_params\": {\n        \"brandId\": \"$request_1:brand.id\"\n      }\n    },\n    {\n      \"uid\": \"request_4\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands\",\n      \"query_params\": {\n        \"limit\": \"1\"\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        },\n        {\n          \"uid\": \"request_4\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")
  .asString();
```

```php Create brand -> create merchant -> retrieve brand -> list brands
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/request-chains', [
  'body' => '{
  "requests": [
    {
      "uid": "request_1",
      "method": "POST",
      "path": "/network/v1/brands",
      "body": {
        "idempotency_key": "idempotency_key",
        "brand": {
          "name": "Brand Name",
          "reference_id": "reference_id"
        }
      }
    },
    {
      "uid": "request_2",
      "method": "POST",
      "path": "/network/v1/merchants",
      "body": {
        "idempotency_key": "idempotency_key",
        "merchant": {
          "name": "Merchant Name",
          "brand_id": "$request_1:brand.id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference_id",
          "address": {
            "country": "US"
          }
        }
      }
    },
    {
      "uid": "request_3",
      "method": "GET",
      "path": "/network/v1/brands/{brandId}",
      "path_params": {
        "brandId": "$request_1:brand.id"
      }
    },
    {
      "uid": "request_4",
      "method": "GET",
      "path": "/network/v1/brands",
      "query_params": {
        "limit": "1"
      }
    }
  ],
  "chains": [
    {
      "requests": [
        {
          "uid": "request_1"
        },
        {
          "uid": "request_2"
        },
        {
          "uid": "request_3"
        },
        {
          "uid": "request_4"
        }
      ],
      "execution_mode": "SEQUENTIAL"
    }
  ]
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Create brand -> create merchant -> retrieve brand -> list brands
var client = new RestClient("https://api.cash.app/management/v1/request-chains");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands/{brandId}\",\n      \"path_params\": {\n        \"brandId\": \"$request_1:brand.id\"\n      }\n    },\n    {\n      \"uid\": \"request_4\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/brands\",\n      \"query_params\": {\n        \"limit\": \"1\"\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        },\n        {\n          \"uid\": \"request_4\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create brand -> create merchant -> retrieve brand -> list brands
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "requests": [
    [
      "uid": "request_1",
      "method": "POST",
      "path": "/network/v1/brands",
      "body": [
        "idempotency_key": "idempotency_key",
        "brand": [
          "name": "Brand Name",
          "reference_id": "reference_id"
        ]
      ]
    ],
    [
      "uid": "request_2",
      "method": "POST",
      "path": "/network/v1/merchants",
      "body": [
        "idempotency_key": "idempotency_key",
        "merchant": [
          "name": "Merchant Name",
          "brand_id": "$request_1:brand.id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference_id",
          "address": ["country": "US"]
        ]
      ]
    ],
    [
      "uid": "request_3",
      "method": "GET",
      "path": "/network/v1/brands/{brandId}",
      "path_params": ["brandId": "$request_1:brand.id"]
    ],
    [
      "uid": "request_4",
      "method": "GET",
      "path": "/network/v1/brands",
      "query_params": ["limit": "1"]
    ]
  ],
  "chains": [
    [
      "requests": [["uid": "request_1"], ["uid": "request_2"], ["uid": "request_3"], ["uid": "request_4"]],
      "execution_mode": "SEQUENTIAL"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/request-chains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Create brand -> create merchant -> create customer request
import requests

url = "https://api.cash.app/management/v1/request-chains"

payload = {
    "requests": [
        {
            "uid": "request_1",
            "method": "POST",
            "path": "/network/v1/brands",
            "body": {
                "idempotency_key": "idempotency_key",
                "brand": {
                    "name": "Brand Name",
                    "reference_id": "reference_id"
                }
            }
        },
        {
            "uid": "request_2",
            "method": "POST",
            "path": "/network/v1/merchants",
            "body": {
                "idempotency_key": "idempotency_key",
                "merchant": {
                    "name": "Merchant Name",
                    "brand_id": "$request_1:brand.id",
                    "country": "US",
                    "currency": "USD",
                    "category": "5432",
                    "reference_id": "reference_id",
                    "address": { "country": "US" }
                }
            }
        },
        {
            "uid": "request_3",
            "method": "POST",
            "path": "/customer-request/v1/requests",
            "body": {
                "idempotency_key": "idempotency_key",
                "request": {
                    "actions": [
                        {
                            "amount": 2500,
                            "currency": "USD",
                            "scope_id": "$request_2:merchant.id",
                            "type": "ONE_TIME_PAYMENT"
                        }
                    ],
                    "channel": "IN_PERSON",
                    "redirect_url": "https://example.com",
                    "reference_id": "string",
                    "metadata": { "key": "value" },
                    "customer_metadata": { "reference_id": "string" }
                }
            }
        }
    ],
    "chains": [
        {
            "requests": [{ "uid": "request_1" }, { "uid": "request_2" }, { "uid": "request_3" }],
            "execution_mode": "SEQUENTIAL"
        }
    ]
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create brand -> create merchant -> create customer request
const url = 'https://api.cash.app/management/v1/request-chains';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"requests":[{"uid":"request_1","method":"POST","path":"/network/v1/brands","body":{"idempotency_key":"idempotency_key","brand":{"name":"Brand Name","reference_id":"reference_id"}}},{"uid":"request_2","method":"POST","path":"/network/v1/merchants","body":{"idempotency_key":"idempotency_key","merchant":{"name":"Merchant Name","brand_id":"$request_1:brand.id","country":"US","currency":"USD","category":"5432","reference_id":"reference_id","address":{"country":"US"}}}},{"uid":"request_3","method":"POST","path":"/customer-request/v1/requests","body":{"idempotency_key":"idempotency_key","request":{"actions":[{"amount":2500,"currency":"USD","scope_id":"$request_2:merchant.id","type":"ONE_TIME_PAYMENT"}],"channel":"IN_PERSON","redirect_url":"https://example.com","reference_id":"string","metadata":{"key":"value"},"customer_metadata":{"reference_id":"string"}}}}],"chains":[{"requests":[{"uid":"request_1"},{"uid":"request_2"},{"uid":"request_3"}],"execution_mode":"SEQUENTIAL"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create brand -> create merchant -> create customer request
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/request-chains"

	payload := strings.NewReader("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/customer-request/v1/requests\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"request\": {\n          \"actions\": [\n            {\n              \"amount\": 2500,\n              \"currency\": \"USD\",\n              \"scope_id\": \"$request_2:merchant.id\",\n              \"type\": \"ONE_TIME_PAYMENT\"\n            }\n          ],\n          \"channel\": \"IN_PERSON\",\n          \"redirect_url\": \"https://example.com\",\n          \"reference_id\": \"string\",\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"customer_metadata\": {\n            \"reference_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create brand -> create merchant -> create customer request
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/request-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/customer-request/v1/requests\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"request\": {\n          \"actions\": [\n            {\n              \"amount\": 2500,\n              \"currency\": \"USD\",\n              \"scope_id\": \"$request_2:merchant.id\",\n              \"type\": \"ONE_TIME_PAYMENT\"\n            }\n          ],\n          \"channel\": \"IN_PERSON\",\n          \"redirect_url\": \"https://example.com\",\n          \"reference_id\": \"string\",\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"customer_metadata\": {\n            \"reference_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Create brand -> create merchant -> create customer request
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/request-chains")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/customer-request/v1/requests\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"request\": {\n          \"actions\": [\n            {\n              \"amount\": 2500,\n              \"currency\": \"USD\",\n              \"scope_id\": \"$request_2:merchant.id\",\n              \"type\": \"ONE_TIME_PAYMENT\"\n            }\n          ],\n          \"channel\": \"IN_PERSON\",\n          \"redirect_url\": \"https://example.com\",\n          \"reference_id\": \"string\",\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"customer_metadata\": {\n            \"reference_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")
  .asString();
```

```php Create brand -> create merchant -> create customer request
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/request-chains', [
  'body' => '{
  "requests": [
    {
      "uid": "request_1",
      "method": "POST",
      "path": "/network/v1/brands",
      "body": {
        "idempotency_key": "idempotency_key",
        "brand": {
          "name": "Brand Name",
          "reference_id": "reference_id"
        }
      }
    },
    {
      "uid": "request_2",
      "method": "POST",
      "path": "/network/v1/merchants",
      "body": {
        "idempotency_key": "idempotency_key",
        "merchant": {
          "name": "Merchant Name",
          "brand_id": "$request_1:brand.id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference_id",
          "address": {
            "country": "US"
          }
        }
      }
    },
    {
      "uid": "request_3",
      "method": "POST",
      "path": "/customer-request/v1/requests",
      "body": {
        "idempotency_key": "idempotency_key",
        "request": {
          "actions": [
            {
              "amount": 2500,
              "currency": "USD",
              "scope_id": "$request_2:merchant.id",
              "type": "ONE_TIME_PAYMENT"
            }
          ],
          "channel": "IN_PERSON",
          "redirect_url": "https://example.com",
          "reference_id": "string",
          "metadata": {
            "key": "value"
          },
          "customer_metadata": {
            "reference_id": "string"
          }
        }
      }
    }
  ],
  "chains": [
    {
      "requests": [
        {
          "uid": "request_1"
        },
        {
          "uid": "request_2"
        },
        {
          "uid": "request_3"
        }
      ],
      "execution_mode": "SEQUENTIAL"
    }
  ]
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Create brand -> create merchant -> create customer request
var client = new RestClient("https://api.cash.app/management/v1/request-chains");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"brand\": {\n          \"name\": \"Brand Name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"merchant\": {\n          \"name\": \"Merchant Name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference_id\",\n          \"address\": {\n            \"country\": \"US\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/customer-request/v1/requests\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"request\": {\n          \"actions\": [\n            {\n              \"amount\": 2500,\n              \"currency\": \"USD\",\n              \"scope_id\": \"$request_2:merchant.id\",\n              \"type\": \"ONE_TIME_PAYMENT\"\n            }\n          ],\n          \"channel\": \"IN_PERSON\",\n          \"redirect_url\": \"https://example.com\",\n          \"reference_id\": \"string\",\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"customer_metadata\": {\n            \"reference_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create brand -> create merchant -> create customer request
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "requests": [
    [
      "uid": "request_1",
      "method": "POST",
      "path": "/network/v1/brands",
      "body": [
        "idempotency_key": "idempotency_key",
        "brand": [
          "name": "Brand Name",
          "reference_id": "reference_id"
        ]
      ]
    ],
    [
      "uid": "request_2",
      "method": "POST",
      "path": "/network/v1/merchants",
      "body": [
        "idempotency_key": "idempotency_key",
        "merchant": [
          "name": "Merchant Name",
          "brand_id": "$request_1:brand.id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference_id",
          "address": ["country": "US"]
        ]
      ]
    ],
    [
      "uid": "request_3",
      "method": "POST",
      "path": "/customer-request/v1/requests",
      "body": [
        "idempotency_key": "idempotency_key",
        "request": [
          "actions": [
            [
              "amount": 2500,
              "currency": "USD",
              "scope_id": "$request_2:merchant.id",
              "type": "ONE_TIME_PAYMENT"
            ]
          ],
          "channel": "IN_PERSON",
          "redirect_url": "https://example.com",
          "reference_id": "string",
          "metadata": ["key": "value"],
          "customer_metadata": ["reference_id": "string"]
        ]
      ]
    ]
  ],
  "chains": [
    [
      "requests": [["uid": "request_1"], ["uid": "request_2"], ["uid": "request_3"]],
      "execution_mode": "SEQUENTIAL"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/request-chains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Upsert brand -> upsert merchant -> create payment
import requests

url = "https://api.cash.app/management/v1/request-chains"

payload = {
    "requests": [
        {
            "uid": "request_1",
            "method": "PUT",
            "path": "/network/v1/brands",
            "body": { "brand": {
                    "name": "brand name",
                    "reference_id": "reference_id"
                } }
        },
        {
            "uid": "request_2",
            "method": "PUT",
            "path": "/network/v1/merchants",
            "body": { "merchant": {
                    "name": "merchant name",
                    "brand_id": "$request_1:brand.id",
                    "country": "US",
                    "currency": "USD",
                    "category": "5432",
                    "reference_id": "reference ID",
                    "address": {
                        "address_line_1": "1215 4th Ave",
                        "address_line_2": "Suite 2300",
                        "locality": "Seattle",
                        "country": "US",
                        "postal_code": "98161-1001",
                        "administrative_district_level_1": "Washington"
                    }
                } }
        },
        {
            "uid": "request_3",
            "method": "POST",
            "path": "/network/v1/payments",
            "body": {
                "idempotency_key": "idempotency_key",
                "payment": {
                    "amount": 100,
                    "currency": "USD",
                    "merchant_id": "$request_2:merchant.id",
                    "grant_id": "GRG_grant-id",
                    "reference_id": "external-id",
                    "capture": True,
                    "metadata": { "key": "value" },
                    "enrichments": { "recurring_series_id": "string" }
                }
            }
        }
    ],
    "chains": [
        {
            "requests": [{ "uid": "request_1" }, { "uid": "request_2" }, { "uid": "request_3" }],
            "execution_mode": "SEQUENTIAL"
        }
    ]
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Upsert brand -> upsert merchant -> create payment
const url = 'https://api.cash.app/management/v1/request-chains';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"requests":[{"uid":"request_1","method":"PUT","path":"/network/v1/brands","body":{"brand":{"name":"brand name","reference_id":"reference_id"}}},{"uid":"request_2","method":"PUT","path":"/network/v1/merchants","body":{"merchant":{"name":"merchant name","brand_id":"$request_1:brand.id","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","country":"US","postal_code":"98161-1001","administrative_district_level_1":"Washington"}}}},{"uid":"request_3","method":"POST","path":"/network/v1/payments","body":{"idempotency_key":"idempotency_key","payment":{"amount":100,"currency":"USD","merchant_id":"$request_2:merchant.id","grant_id":"GRG_grant-id","reference_id":"external-id","capture":true,"metadata":{"key":"value"},"enrichments":{"recurring_series_id":"string"}}}}],"chains":[{"requests":[{"uid":"request_1"},{"uid":"request_2"},{"uid":"request_3"}],"execution_mode":"SEQUENTIAL"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Upsert brand -> upsert merchant -> create payment
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/request-chains"

	payload := strings.NewReader("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"brand\": {\n          \"name\": \"brand name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/payments\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"payment\": {\n          \"amount\": 100,\n          \"currency\": \"USD\",\n          \"merchant_id\": \"$request_2:merchant.id\",\n          \"grant_id\": \"GRG_grant-id\",\n          \"reference_id\": \"external-id\",\n          \"capture\": true,\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"enrichments\": {\n            \"recurring_series_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Upsert brand -> upsert merchant -> create payment
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/request-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"brand\": {\n          \"name\": \"brand name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/payments\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"payment\": {\n          \"amount\": 100,\n          \"currency\": \"USD\",\n          \"merchant_id\": \"$request_2:merchant.id\",\n          \"grant_id\": \"GRG_grant-id\",\n          \"reference_id\": \"external-id\",\n          \"capture\": true,\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"enrichments\": {\n            \"recurring_series_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Upsert brand -> upsert merchant -> create payment
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/request-chains")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"brand\": {\n          \"name\": \"brand name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/payments\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"payment\": {\n          \"amount\": 100,\n          \"currency\": \"USD\",\n          \"merchant_id\": \"$request_2:merchant.id\",\n          \"grant_id\": \"GRG_grant-id\",\n          \"reference_id\": \"external-id\",\n          \"capture\": true,\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"enrichments\": {\n            \"recurring_series_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")
  .asString();
```

```php Upsert brand -> upsert merchant -> create payment
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/request-chains', [
  'body' => '{
  "requests": [
    {
      "uid": "request_1",
      "method": "PUT",
      "path": "/network/v1/brands",
      "body": {
        "brand": {
          "name": "brand name",
          "reference_id": "reference_id"
        }
      }
    },
    {
      "uid": "request_2",
      "method": "PUT",
      "path": "/network/v1/merchants",
      "body": {
        "merchant": {
          "name": "merchant name",
          "brand_id": "$request_1:brand.id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference ID",
          "address": {
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "country": "US",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
          }
        }
      }
    },
    {
      "uid": "request_3",
      "method": "POST",
      "path": "/network/v1/payments",
      "body": {
        "idempotency_key": "idempotency_key",
        "payment": {
          "amount": 100,
          "currency": "USD",
          "merchant_id": "$request_2:merchant.id",
          "grant_id": "GRG_grant-id",
          "reference_id": "external-id",
          "capture": true,
          "metadata": {
            "key": "value"
          },
          "enrichments": {
            "recurring_series_id": "string"
          }
        }
      }
    }
  ],
  "chains": [
    {
      "requests": [
        {
          "uid": "request_1"
        },
        {
          "uid": "request_2"
        },
        {
          "uid": "request_3"
        }
      ],
      "execution_mode": "SEQUENTIAL"
    }
  ]
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Upsert brand -> upsert merchant -> create payment
var client = new RestClient("https://api.cash.app/management/v1/request-chains");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/brands\",\n      \"body\": {\n        \"brand\": {\n          \"name\": \"brand name\",\n          \"reference_id\": \"reference_id\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"$request_1:brand.id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          }\n        }\n      }\n    },\n    {\n      \"uid\": \"request_3\",\n      \"method\": \"POST\",\n      \"path\": \"/network/v1/payments\",\n      \"body\": {\n        \"idempotency_key\": \"idempotency_key\",\n        \"payment\": {\n          \"amount\": 100,\n          \"currency\": \"USD\",\n          \"merchant_id\": \"$request_2:merchant.id\",\n          \"grant_id\": \"GRG_grant-id\",\n          \"reference_id\": \"external-id\",\n          \"capture\": true,\n          \"metadata\": {\n            \"key\": \"value\"\n          },\n          \"enrichments\": {\n            \"recurring_series_id\": \"string\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        },\n        {\n          \"uid\": \"request_3\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Upsert brand -> upsert merchant -> create payment
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "requests": [
    [
      "uid": "request_1",
      "method": "PUT",
      "path": "/network/v1/brands",
      "body": ["brand": [
          "name": "brand name",
          "reference_id": "reference_id"
        ]]
    ],
    [
      "uid": "request_2",
      "method": "PUT",
      "path": "/network/v1/merchants",
      "body": ["merchant": [
          "name": "merchant name",
          "brand_id": "$request_1:brand.id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference ID",
          "address": [
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "country": "US",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
          ]
        ]]
    ],
    [
      "uid": "request_3",
      "method": "POST",
      "path": "/network/v1/payments",
      "body": [
        "idempotency_key": "idempotency_key",
        "payment": [
          "amount": 100,
          "currency": "USD",
          "merchant_id": "$request_2:merchant.id",
          "grant_id": "GRG_grant-id",
          "reference_id": "external-id",
          "capture": true,
          "metadata": ["key": "value"],
          "enrichments": ["recurring_series_id": "string"]
        ]
      ]
    ]
  ],
  "chains": [
    [
      "requests": [["uid": "request_1"], ["uid": "request_2"], ["uid": "request_3"]],
      "execution_mode": "SEQUENTIAL"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/request-chains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Retrieve fee plan -> upsert merchant
import requests

url = "https://api.cash.app/management/v1/request-chains"

payload = {
    "requests": [
        {
            "uid": "request_1",
            "method": "GET",
            "path": "/network/v1/fee-plans/FEE_fee-plan-id"
        },
        {
            "uid": "request_2",
            "method": "PUT",
            "path": "/network/v1/merchants",
            "body": { "merchant": {
                    "name": "merchant name",
                    "brand_id": "BRAND_brand-id",
                    "country": "US",
                    "currency": "USD",
                    "category": "5432",
                    "reference_id": "reference ID",
                    "address": {
                        "address_line_1": "1215 4th Ave",
                        "address_line_2": "Suite 2300",
                        "locality": "Seattle",
                        "country": "US",
                        "postal_code": "98161-1001",
                        "administrative_district_level_1": "Washington"
                    },
                    "default_fee_plans": { "in_app_fee_plan_id": "$request_1:fee_plan.id" }
                } }
        }
    ],
    "chains": [
        {
            "requests": [{ "uid": "request_1" }, { "uid": "request_2" }],
            "execution_mode": "SEQUENTIAL"
        }
    ]
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Retrieve fee plan -> upsert merchant
const url = 'https://api.cash.app/management/v1/request-chains';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"requests":[{"uid":"request_1","method":"GET","path":"/network/v1/fee-plans/FEE_fee-plan-id"},{"uid":"request_2","method":"PUT","path":"/network/v1/merchants","body":{"merchant":{"name":"merchant name","brand_id":"BRAND_brand-id","country":"US","currency":"USD","category":"5432","reference_id":"reference ID","address":{"address_line_1":"1215 4th Ave","address_line_2":"Suite 2300","locality":"Seattle","country":"US","postal_code":"98161-1001","administrative_district_level_1":"Washington"},"default_fee_plans":{"in_app_fee_plan_id":"$request_1:fee_plan.id"}}}}],"chains":[{"requests":[{"uid":"request_1"},{"uid":"request_2"}],"execution_mode":"SEQUENTIAL"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Retrieve fee plan -> upsert merchant
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/request-chains"

	payload := strings.NewReader("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/fee-plans/FEE_fee-plan-id\"\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"BRAND_brand-id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          },\n          \"default_fee_plans\": {\n            \"in_app_fee_plan_id\": \"$request_1:fee_plan.id\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Retrieve fee plan -> upsert merchant
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/request-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/fee-plans/FEE_fee-plan-id\"\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"BRAND_brand-id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          },\n          \"default_fee_plans\": {\n            \"in_app_fee_plan_id\": \"$request_1:fee_plan.id\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Retrieve fee plan -> upsert merchant
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/request-chains")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/fee-plans/FEE_fee-plan-id\"\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"BRAND_brand-id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          },\n          \"default_fee_plans\": {\n            \"in_app_fee_plan_id\": \"$request_1:fee_plan.id\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")
  .asString();
```

```php Retrieve fee plan -> upsert merchant
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/request-chains', [
  'body' => '{
  "requests": [
    {
      "uid": "request_1",
      "method": "GET",
      "path": "/network/v1/fee-plans/FEE_fee-plan-id"
    },
    {
      "uid": "request_2",
      "method": "PUT",
      "path": "/network/v1/merchants",
      "body": {
        "merchant": {
          "name": "merchant name",
          "brand_id": "BRAND_brand-id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference ID",
          "address": {
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "country": "US",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
          },
          "default_fee_plans": {
            "in_app_fee_plan_id": "$request_1:fee_plan.id"
          }
        }
      }
    }
  ],
  "chains": [
    {
      "requests": [
        {
          "uid": "request_1"
        },
        {
          "uid": "request_2"
        }
      ],
      "execution_mode": "SEQUENTIAL"
    }
  ]
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Retrieve fee plan -> upsert merchant
var client = new RestClient("https://api.cash.app/management/v1/request-chains");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"GET\",\n      \"path\": \"/network/v1/fee-plans/FEE_fee-plan-id\"\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PUT\",\n      \"path\": \"/network/v1/merchants\",\n      \"body\": {\n        \"merchant\": {\n          \"name\": \"merchant name\",\n          \"brand_id\": \"BRAND_brand-id\",\n          \"country\": \"US\",\n          \"currency\": \"USD\",\n          \"category\": \"5432\",\n          \"reference_id\": \"reference ID\",\n          \"address\": {\n            \"address_line_1\": \"1215 4th Ave\",\n            \"address_line_2\": \"Suite 2300\",\n            \"locality\": \"Seattle\",\n            \"country\": \"US\",\n            \"postal_code\": \"98161-1001\",\n            \"administrative_district_level_1\": \"Washington\"\n          },\n          \"default_fee_plans\": {\n            \"in_app_fee_plan_id\": \"$request_1:fee_plan.id\"\n          }\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Retrieve fee plan -> upsert merchant
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "requests": [
    [
      "uid": "request_1",
      "method": "GET",
      "path": "/network/v1/fee-plans/FEE_fee-plan-id"
    ],
    [
      "uid": "request_2",
      "method": "PUT",
      "path": "/network/v1/merchants",
      "body": ["merchant": [
          "name": "merchant name",
          "brand_id": "BRAND_brand-id",
          "country": "US",
          "currency": "USD",
          "category": "5432",
          "reference_id": "reference ID",
          "address": [
            "address_line_1": "1215 4th Ave",
            "address_line_2": "Suite 2300",
            "locality": "Seattle",
            "country": "US",
            "postal_code": "98161-1001",
            "administrative_district_level_1": "Washington"
          ],
          "default_fee_plans": ["in_app_fee_plan_id": "$request_1:fee_plan.id"]
        ]]
    ]
  ],
  "chains": [
    [
      "requests": [["uid": "request_1"], ["uid": "request_2"]],
      "execution_mode": "SEQUENTIAL"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/request-chains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Create API key -> update webhook endpoint
import requests

url = "https://api.cash.app/management/v1/request-chains"

payload = {
    "requests": [
        {
            "uid": "request_1",
            "method": "POST",
            "path": "/management/v1/api-keys",
            "body": {
                "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
                "api_key": {
                    "scopes": ["PAYMENTS_READ"],
                    "reference_id": "string"
                }
            }
        },
        {
            "uid": "request_2",
            "method": "PATCH",
            "path": "/management/v1/webhook-endpoints/WC_webhook-configuration-id",
            "body": { "webhook_endpoint": { "api_key_id": "$request_1:api_key.id" } }
        }
    ],
    "chains": [
        {
            "requests": [{ "uid": "request_1" }, { "uid": "request_2" }],
            "execution_mode": "SEQUENTIAL"
        }
    ]
}
headers = {
    "Accept": "Accept",
    "X-Region": "X-Region",
    "X-Signature": "X-Signature",
    "User-Agent": "User-Agent",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create API key -> update webhook endpoint
const url = 'https://api.cash.app/management/v1/request-chains';
const options = {
  method: 'POST',
  headers: {
    Accept: 'Accept',
    'X-Region': 'X-Region',
    'X-Signature': 'X-Signature',
    'User-Agent': 'User-Agent',
    'Content-Type': 'application/json'
  },
  body: '{"requests":[{"uid":"request_1","method":"POST","path":"/management/v1/api-keys","body":{"idempotency_key":"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19","api_key":{"scopes":["PAYMENTS_READ"],"reference_id":"string"}}},{"uid":"request_2","method":"PATCH","path":"/management/v1/webhook-endpoints/WC_webhook-configuration-id","body":{"webhook_endpoint":{"api_key_id":"$request_1:api_key.id"}}}],"chains":[{"requests":[{"uid":"request_1"},{"uid":"request_2"}],"execution_mode":"SEQUENTIAL"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create API key -> update webhook endpoint
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cash.app/management/v1/request-chains"

	payload := strings.NewReader("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/management/v1/api-keys\",\n      \"body\": {\n        \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n        \"api_key\": {\n          \"scopes\": [\n            \"PAYMENTS_READ\"\n          ],\n          \"reference_id\": \"string\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PATCH\",\n      \"path\": \"/management/v1/webhook-endpoints/WC_webhook-configuration-id\",\n      \"body\": {\n        \"webhook_endpoint\": {\n          \"api_key_id\": \"$request_1:api_key.id\"\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "Accept")
	req.Header.Add("X-Region", "X-Region")
	req.Header.Add("X-Signature", "X-Signature")
	req.Header.Add("User-Agent", "User-Agent")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create API key -> update webhook endpoint
require 'uri'
require 'net/http'

url = URI("https://api.cash.app/management/v1/request-chains")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'Accept'
request["X-Region"] = 'X-Region'
request["X-Signature"] = 'X-Signature'
request["User-Agent"] = 'User-Agent'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/management/v1/api-keys\",\n      \"body\": {\n        \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n        \"api_key\": {\n          \"scopes\": [\n            \"PAYMENTS_READ\"\n          ],\n          \"reference_id\": \"string\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PATCH\",\n      \"path\": \"/management/v1/webhook-endpoints/WC_webhook-configuration-id\",\n      \"body\": {\n        \"webhook_endpoint\": {\n          \"api_key_id\": \"$request_1:api_key.id\"\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Create API key -> update webhook endpoint
HttpResponse<String> response = Unirest.post("https://api.cash.app/management/v1/request-chains")
  .header("Accept", "Accept")
  .header("X-Region", "X-Region")
  .header("X-Signature", "X-Signature")
  .header("User-Agent", "User-Agent")
  .header("Content-Type", "application/json")
  .body("{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/management/v1/api-keys\",\n      \"body\": {\n        \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n        \"api_key\": {\n          \"scopes\": [\n            \"PAYMENTS_READ\"\n          ],\n          \"reference_id\": \"string\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PATCH\",\n      \"path\": \"/management/v1/webhook-endpoints/WC_webhook-configuration-id\",\n      \"body\": {\n        \"webhook_endpoint\": {\n          \"api_key_id\": \"$request_1:api_key.id\"\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}")
  .asString();
```

```php Create API key -> update webhook endpoint
<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cash.app/management/v1/request-chains', [
  'body' => '{
  "requests": [
    {
      "uid": "request_1",
      "method": "POST",
      "path": "/management/v1/api-keys",
      "body": {
        "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
        "api_key": {
          "scopes": [
            "PAYMENTS_READ"
          ],
          "reference_id": "string"
        }
      }
    },
    {
      "uid": "request_2",
      "method": "PATCH",
      "path": "/management/v1/webhook-endpoints/WC_webhook-configuration-id",
      "body": {
        "webhook_endpoint": {
          "api_key_id": "$request_1:api_key.id"
        }
      }
    }
  ],
  "chains": [
    {
      "requests": [
        {
          "uid": "request_1"
        },
        {
          "uid": "request_2"
        }
      ],
      "execution_mode": "SEQUENTIAL"
    }
  ]
}',
  'headers' => [
    'Accept' => 'Accept',
    'Content-Type' => 'application/json',
    'User-Agent' => 'User-Agent',
    'X-Region' => 'X-Region',
    'X-Signature' => 'X-Signature',
  ],
]);

echo $response->getBody();
```

```csharp Create API key -> update webhook endpoint
var client = new RestClient("https://api.cash.app/management/v1/request-chains");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "Accept");
request.AddHeader("X-Region", "X-Region");
request.AddHeader("X-Signature", "X-Signature");
request.AddHeader("User-Agent", "User-Agent");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"requests\": [\n    {\n      \"uid\": \"request_1\",\n      \"method\": \"POST\",\n      \"path\": \"/management/v1/api-keys\",\n      \"body\": {\n        \"idempotency_key\": \"e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19\",\n        \"api_key\": {\n          \"scopes\": [\n            \"PAYMENTS_READ\"\n          ],\n          \"reference_id\": \"string\"\n        }\n      }\n    },\n    {\n      \"uid\": \"request_2\",\n      \"method\": \"PATCH\",\n      \"path\": \"/management/v1/webhook-endpoints/WC_webhook-configuration-id\",\n      \"body\": {\n        \"webhook_endpoint\": {\n          \"api_key_id\": \"$request_1:api_key.id\"\n        }\n      }\n    }\n  ],\n  \"chains\": [\n    {\n      \"requests\": [\n        {\n          \"uid\": \"request_1\"\n        },\n        {\n          \"uid\": \"request_2\"\n        }\n      ],\n      \"execution_mode\": \"SEQUENTIAL\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create API key -> update webhook endpoint
import Foundation

let headers = [
  "Accept": "Accept",
  "X-Region": "X-Region",
  "X-Signature": "X-Signature",
  "User-Agent": "User-Agent",
  "Content-Type": "application/json"
]
let parameters = [
  "requests": [
    [
      "uid": "request_1",
      "method": "POST",
      "path": "/management/v1/api-keys",
      "body": [
        "idempotency_key": "e345c3fb-1caa-46fd-b0d3-aa6c7b00ab19",
        "api_key": [
          "scopes": ["PAYMENTS_READ"],
          "reference_id": "string"
        ]
      ]
    ],
    [
      "uid": "request_2",
      "method": "PATCH",
      "path": "/management/v1/webhook-endpoints/WC_webhook-configuration-id",
      "body": ["webhook_endpoint": ["api_key_id": "$request_1:api_key.id"]]
    ]
  ],
  "chains": [
    [
      "requests": [["uid": "request_1"], ["uid": "request_2"]],
      "execution_mode": "SEQUENTIAL"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cash.app/management/v1/request-chains")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

---

# ErrorResponse

<EndpointSchemaSnippet endpoint="GET /management-error-response-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "errors": [
      {
        "category": "INVALID_REQUEST_ERROR",
        "code": "MISSING_REQUIRED_FIELD",
        "detail": "Missing required parameter.",
        "field": "field_a[2].field_b"
      }
    ]
  }
  ```
</Aside>

---

# Response

<EndpointSchemaSnippet endpoint="GET /response-schema-test" selector="response.body" />

<Aside>
  ```json Example
  {
    "request_uid": "string",
    "execution_status": "EXECUTED",
    "path": "/network/v1/brands",
    "method": "GET",
    "status_code": 0,
    "body": {},
    "completed_at": "2021-01-01T00:00:00Z"
  }
  ```
</Aside>