> This page is for Cash App Pay Partner API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.cash.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server. # 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. 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](/_fern-img/fc3ac8108819fc587518607023d5d7c81228c5fc0ff43cacd6b315615e2af6ed.webp) ## 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. |