Cash App Pay Network API
Server-side REST API that registers merchants and processes payments using grants - the core Cash App Pay payment-processing surface for PSP partners.
Cash App Pay Network API is one of 12 APIs that Cash App publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Payments and Network API. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference.
This API exposes 44 operations across 34 paths, organized into 9 resource areas, and defines 145 schemas. It is described by OpenAPI 3.1.0, at version 1.0.0.
Requests are made against 2 base URLs: https://api.cash.app/network/v1, https://sandbox.api.cash.app/network/v1.
44 operations
34 paths
145 schemas
1 DELETE22 GET2 PATCH17 POST2 PUT
Metadata
The identity and technical contract details declared by the specification.
Paths & Operations 44
Across 34 paths, the API surfaces 44 operations — 1 DELETE, 22 GET, 2 PATCH, 17 POST, 2 PUT. They span 9 resource areas: brands, merchants, customers, payments, payouts, balances, refunds, disputes, feePlans. Each is listed below with its method, path, parameters, and response codes.
brands 5
GET
/brands
List brands
POST
/brands
Create brand
PUT
/brands
Upsert brand
GET
/brands/{brand_id}
Retrieve brand
PATCH
/brands/{brand_id}
Update brand
merchants 5
GET
/merchants
List merchants
POST
/merchants
Create merchant
PUT
/merchants
Upsert merchant
GET
/merchants/{merchant_id}
Retrieve merchant
PATCH
/merchants/{merchant_id}
Update merchant
customers 5
GET
/customers
List customers
GET
/customers/{customer_id}
Retrieve customer
GET
/customers/{customer_id}/grants/{grant_id}
Retrieve customer grant
GET
/customers/{customer_id}/grants
List customer grants
POST
/customers/{customer_id}/grants/{grant_id}/revoke
Revoke customer grant
payments 7
GET
/payments
List payments
POST
/payments
Create payment
GET
/payments/{payment_id}
Retrieve payment
POST
/payments/{payment_id}/authorizations
Create incremental authorization
POST
/payments/{payment_id}/capture
Capture payment
POST
/payments/{payment_id}/void
Void payment
POST
/payments/void-by-idempotency-key
Void payment by idempotency key
payouts 3
GET
/payouts
List payouts
POST
/payouts
Create payout
GET
/payouts/{payout_id}
Retrieve payout
balances 2
GET
/balances
List balances
GET
/balances/{balance_id}
Retrieve balance
refunds 6
GET
/refunds
List refunds
POST
/refunds
Create refund
GET
/refunds/{refund_id}
Retrieve refund
POST
/refunds/{refund_id}/capture
Capture refund
POST
/refunds/{refund_id}/void
Void refund
POST
/refunds/void-by-idempotency-key
Void refund by idempotency key
disputes 9
GET
/disputes
List disputes
GET
/disputes/{dispute_id}
Retrieve dispute
POST
/disputes/{dispute_id}/accept
Accept dispute
POST
/disputes/{dispute_id}/challenge
Challenge dispute
GET
/disputes/{dispute_id}/evidence
List dispute evidence
POST
/disputes/{dispute_id}/evidence-text
Create dispute evidence text
POST
/disputes/{dispute_id}/evidence-file
Create dispute evidence file
DELETE
/disputes/{dispute_id}/evidence/{evidence_id}
Delete dispute evidence
GET
/disputes/{dispute_id}/evidence/{evidence_id}
Retrieve dispute evidence
feePlans 2
GET
/fee-plans/{fee_plan_id}
Retrieve Fee Plan
GET
/fee-plans
List fee plans
Schemas 145
The contract defines 145 schemas that model the data the API accepts and returns. The most detailed are Payment (22 properties), Payout (18 properties), Merchant (14 properties), Refund (13 properties). Each schema is shown below with its type and property counts.
Metadata
object
Freeform key-value pairs of arbitrary data associated with this resource. Keys and values must be passed as strings and not contain any personally identifiable…
Brand
object
A brand is the entity a customer perceives that they are transacting with.
8 properties
5 required
Brands_list-brands_Response_200
object
2 properties
1 required
ErrorCategory
string
The high-level reason the error occurred.
Error
object
Represents an error encountered during a request to the API.
4 properties
2 required
ErrorResponse
object
1 property
1 required
IdempotencyKey
string
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see [Idempotency](/cash-…
BrandsPostRequestBodyContentApplicationJsonSchemaBrand
object
Details about the brand to create.
5 properties
2 required
Brands_create-brand_Response_201
object
1 property
BrandsPutRequestBodyContentApplicationJsonSchemaBrand
object
Details about the brand to create or update.
5 properties
2 required
Brands_upsert-brand_Response_200
object
1 property
Brands_retrieve-brand_Response_200
object
1 property
1 required
BrandsBrandIdPatchRequestBodyContentApplicationJsonSchemaBrand
object
Details about the brand to update
5 properties
Brands_update-brand_Response_200
object
1 property
Country
string
Indicates the country associated with an entity. Values are from the [ISO-3166 Alpha-2](https://www.iso.org/iso-3166-country-codes.html) specification. Current…
Currency
string
Indicates the country associated with an entity. Values are from the [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html) specification. Curren…
Category
string
The merchant category code associated with the entity. Values are from the [ISO-18245 specification](https://www.iso.org/standard/33365.html).
MerchantStatus
string
Whether or not this merchant can be used to accept payments or issue refunds. - ACTIVE: The merchant can accept payments or issue refunds. - RISKDISABLED: Cash…
Address
object
Where this entity is located
6 properties
1 required
MerchantFeePlans
object
Merchant fee plans contains the IDs of the different fee plans for a merchant. These IDs represent the processing fees that merchants will be charged for proce…
3 properties
Merchant
object
A merchant represents a depository account when processing payments from Cash App customers. Merchants do not have direct access to Cash App, so processed paym…
14 properties
11 required
Merchants_list-merchants_Response_200
object
2 properties
1 required
List-merchantsRequestBadRequestError
object
1 property
1 required
MerchantsPostRequestBodyContentApplicationJsonSchemaMerchant
object
Details about the merchant to create.
10 properties
7 required
Merchants_create-merchant_Response_201
object
1 property
1 required
MerchantsPutRequestBodyContentApplicationJsonSchemaMerchant
object
Details about the merchant to create or update.
10 properties
7 required
Merchants_upsert-merchant_Response_200
object
1 property
1 required
Merchants_retrieve-merchant_Response_200
object
1 property
1 required
MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchantStatus
string
Whether or not this merchant can be used to accept payments or issue refunds. Note: when the value is PENDING, COMPLIANCEDISABLED, or RISKDISABLED, the status…
MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchant
object
Details about the merchant to update.
11 properties
Merchants_update-merchant_Response_200
object
1 property
Customer
object
3 properties
2 required
Customers_list-customers_Response_200
object
2 properties
1 required
Customers_retrieve-customer_Response_200
object
1 property
1 required
OneTimePaymentActionType
string
The type of the action (ONETIMEPAYMENT).
OneTimePaymentAction
object
Describes an intent for a client to charge a customer a given amount. Note the following restrictions when using this action: - If no amount is provided to the…
4 properties
2 required
OnFilePaymentActionType
string
The type of the action (ONFILEPAYMENT).
OnFilePaymentAction
object
Describes an intent for a client to store a customer's account, allowing a client to create payments or issue refunds for it on a recurring basis.
3 properties
2 required
OnFileDepositActionType
string
The type of the action (ONFILEDEPOSIT).
OnFileDepositAction
object
Describes an intent for a client to deposit funds into the Cash App account balances in perpetuity until the Cash App account revokes the grant.
3 properties
3 required
LinkAccountActionType
string
The type of the action (LINKACCOUNT).
LinkAccountAction
object
Describes an intent for a client to manage a customer's merchant profiles in Cash App.
1 property
1 required
Action
Represents what the client intends to do to a customer if given authorization.
GrantStatus
string
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 n…
GrantType
string
Describes whether this grant can be only be used once (ONETIME) or repeatedly (EXTENDED).
Channel
string
How the customer is expected to interact with the request. - INPERSON: The customer presents or scans a QR code at a physical location to approve the request.…
Grant
object
Describes a grant that can be used to perform actions specified in a customer request using the Network API.
10 properties
9 required
Customers_retrieve-customer-grant_Response_200
object
1 property
1 required
Customers_list-customer-grants_Response_200
object
2 properties
1 required
Customers_revoke-customer-grant_Response_200
object
1 property
1 required
PaymentStatus
string
The step of the payment processing lifecycle that this payment is currently at. - AUTHORIZED - CAPTURED - VOIDED - DECLINED
PaymentEnrichmentsInitiationActor
string
The party who initiated the payment. - CUSTOMER - MERCHANT
PaymentEnrichmentsInitiation
object
If present, provides information about transaction initiation.
1 property
1 required
PaymentEnrichmentsRestrictedCategoriesItems
string
PaymentEnrichments
object
Describes optional fields beyond core payment information to supplement payment processing. Enrichments provide additional context about a payment, which can i…
4 properties
FeeRate
object
A fee rate contains the components of a fee charged by Cash App to partners for a given payment.
2 properties
AuthorizationStatus
string
The step of the authorization processing lifecycle that this authorization is currently at. Allowed values: - AUTHORIZED - DECLINED
Authorization
object
Represents an authorization update for a payment
10 properties
7 required
Payment
object
22 properties
13 required
Payments_list-payments_Response_200
object
2 properties
1 required
PaymentsPostRequestBodyContentApplicationJsonSchemaPayment
object
Data about the payment to create.
8 properties
4 required
Payments_create-payment_Response_201
object
1 property
Create-paymentRequestBadRequestError
object
2 properties
1 required
Payments_retrieve-payment_Response_200
object
1 property
1 required
Retrieve-paymentRequestNotFoundError
object
1 property
1 required
PaymentsPaymentIdAuthorizationsPostRequestBodyContentApplicationJsonSchemaAuthorization
object
Details about the authorization to create.
4 properties
2 required
Payments_create-payment-authorization_Response_201
object
1 property
1 required
Create-payment-authorizationRequestBadRequestError
object
2 properties
1 required
Payments_capture-payment_Response_200
object
1 property
1 required
Payments_void-payment_Response_200
object
1 property
1 required
Payments_void-payment-by-idempotency-key_Response_200
object
1 property
1 required
PayoutStatus
string
The step of the payout processing lifecycle that this payout is currently at. - CAPTURED - Payout is captured and funds have been sent - DECLINED - Payout was…
PayoutPurpose
string
The purpose or intent of the payout.
Payout
object
18 properties
7 required
Payouts_list-payouts_Response_200
object
2 properties
1 required
PayoutsPostRequestBodyContentApplicationJsonSchemaPayout
object
Data about the payout to create.
9 properties
7 required
Payouts_create-payout_Response_201
object
1 property
Create-payoutRequestBadRequestError
object
2 properties
1 required
Payouts_retrieve-payout_Response_200
object
1 property
1 required
Retrieve-payoutRequestNotFoundError
object
1 property
1 required
BalancesGetParametersType
string
BalanceType
string
The type of balance.
Balance
object
7 properties
5 required
Balances_list-balances_Response_200
object
2 properties
1 required
Balances_retrieve-balance_Response_200
object
1 property
1 required
Retrieve-balanceRequestNotFoundError
object
1 property
1 required
RefundStatus
string
The step of the refund processing lifecycle that this refund is currently at. - AUTHORIZED - CAPTURED - VOIDED - DECLINED
Refund
object
13 properties
8 required
Refunds_list-refunds_Response_200
object
2 properties
1 required
RefundsPostRequestBodyContentApplicationJsonSchemaRefund
object
Details about the refund to create.
7 properties
3 required
Refunds_create-refund_Response_200
object
1 property
1 required
Create-refundRequestBadRequestError
object
2 properties
1 required
Refunds_retrieve-refund_Response_200
object
1 property
1 required
Refunds_capture-refund_Response_200
object
1 property
1 required
Refunds_void-refund_Response_200
object
1 property
1 required
Refunds_void-refund-by-idempotency-key_Response_200
object
1 property
1 required
DisputeReason
string
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…
DisputeSettlementWithholding
string
Indicates if the disputed amount has already been withheld from a settlement or not. Current values: - NOTWITHHELD: The disputed amount has not yet been withhe…
DisputeState
string
The step in the dispute lifecycle that this dispute is currently at: - RESPONSEREQUIRED - NORESPONSEREQUIRED - PROCESSING - ACCEPTED - WON - PARTIALLYWON - LOST
Dispute
object
Represents a dispute initiated by a customer within Cash App or the customer's linked bank
11 properties
9 required
Disputes_list-disputes_Response_200
object
2 properties
1 required
Disputes_retrieve-dispute_Response_200
object
1 property
1 required
Disputes_accept-dispute_Response_200
object
1 property
Disputes_challenge-dispute_Response_200
object
1 property
1 required
DisputeEvidenceCategory
string
Describes what type of information is contained in this piece of evidence. Current values: - GENERICEVIDENCE: Default evidence type used if no other category a…
DisputeEvidenceFileContentType
string
The MIME type of the uploaded file. Current values: - application/pdf - image/heic - image/heif - image/jpeg - image/png - image/tiff
DisputeEvidenceFile
object
If the evidence is of type FILE, contains metadata about the binary file uploaded as evidence.
2 properties
2 required
DisputeEvidenceType
string
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 uplo…
DisputeEvidence
object
8 properties
5 required
Disputes_list-dispute-evidence_Response_200
object
2 properties
1 required
DisputesDisputeIdEvidenceTextPostRequestBodyContentApplicationJsonSchemaEvidenceCategory
string
Describes what type of information is contained in this piece of evidence. Current values: - GENERICEVIDENCE: Default evidence type used if no other category a…
DisputesDisputeIdEvidenceTextPostRequestBodyContentApplicationJsonSchemaEvidence
object
Details about the evidence to create.
3 properties
2 required
Disputes_create-dispute-evidence-text_Response_201
object
1 property
DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceCategory
string
Describes what type of information is contained in this piece of evidence. Current values: - GENERICEVIDENCE: Default evidence type used if no other category a…
DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceFileContentType
string
The MIME type of the uploaded file. Current values: - application/pdf - image/heic - image/heif - image/jpeg - image/png - image/tiff
DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidenceFile
object
Metadata about the uploaded file.
2 properties
2 required
DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequestEvidence
object
Details about the evidence to create.
3 properties
2 required
DisputesDisputeIdEvidenceFilePostRequestBodyContentMultipartFormDataSchemaRequest
object
JSON-encoded payload describing the contents of the file uploaded
2 properties
Disputes_create-dispute-evidence-file_Response_201
object
1 property
1 required
Disputes_delete-dispute-evidence_Response_200
object
Empty response body
Disputes_retrieve-dispute-evidence_Response_200
object
1 property
1 required
FeePlan
object
The full fee plan that PSPs can use to set the buy rates for specific merchants.
9 properties
6 required
Fee Plans_retrieve-fee-plan_Response_200
object
1 property
1 required
FeePlansGetParametersStatus
string
Fee Plans_list-fee-plans_Response_200
object
2 properties
WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the merchant data immediately after the merchant's status changed.
1 property
1 required
WebhooksMerchantStatusUpdatedPayloadContentApplicationJsonSchemaData
object
Data about the merchant that had a status change.
3 properties
3 required
WebhooksGrantCreatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the grant immediately after the grant was created.
1 property
1 required
WebhooksGrantCreatedPayloadContentApplicationJsonSchemaData
object
Data about the grant that was created.
3 properties
3 required
WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the grant immediately after the grant's status changed.
1 property
1 required
WebhooksGrantStatusUpdatedPayloadContentApplicationJsonSchemaData
object
Data about the grant that had a status change.
3 properties
3 required
WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the customer immediately after the customer was created.
1 property
1 required
WebhooksCustomerCreatedPayloadContentApplicationJsonSchemaData
object
Data about the Customer that was created.
3 properties
3 required
WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the customer immediately after the customer was updated.
1 property
1 required
WebhooksCustomerUpdatedPayloadContentApplicationJsonSchemaData
object
Data about the Customer that was updated.
3 properties
3 required
WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the customer immediately after the customer was deleted.
1 property
1 required
WebhooksCustomerDeletedPayloadContentApplicationJsonSchemaData
object
Data about the Customer that was deleted.
3 properties
3 required
WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the payment data immediately after the payment's status changed.
1 property
1 required
WebhooksPaymentStatusUpdatedPayloadContentApplicationJsonSchemaData
object
Data about the payment that had a status change.
3 properties
3 required
WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the refund immediately after the refund's status changed.
1 property
1 required
WebhooksRefundStatusUpdatedPayloadContentApplicationJsonSchemaData
object
Data about the refund that had a status change.
3 properties
3 required
WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the dispute immediately after the dispute was created.
1 property
1 required
WebhooksDisputeCreatedPayloadContentApplicationJsonSchemaData
object
Data about the dispute that was created.
3 properties
3 required
WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaDataObject
object
A snapshot of the dispute immediately after the dispute's status was updated.
1 property
1 required
WebhooksDisputeStatusUpdatedPayloadContentApplicationJsonSchemaData
object
Data about the dispute that was updated.
3 properties
3 required
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from Cash App 11
Other APIs Cash App publishes across the network.
Cash App Pay Customer Request API
Cash App Pay Management API
Afterpay Payments API
Afterpay Checkouts API
Afterpay Orders API
Afterpay Configuration API
Afterpay Disputes API
Afterpay Grants API
Add Cash App Pay to Your Site (Grants) API
Afterpay Service Status API
Afterpay Billing Agreements API (Deprecated)
#Payments#Network API