> 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.
### Schema (`response.body`)
```yaml
openapi: 3.1.0
info:
title: API
version: 1.0.0
paths:
/payments:
post:
operationId: subpackagePayments_create-payment
summary: Create payment
description: |-
Creates a payment from a customer to a merchant.
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.
**This endpoint is not rate limited.**
Scopes: `PAYMENTS_WRITE`
tags:
- subpackage_payments
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/payments_CreatePaymentResponse'
'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.
**`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.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequestBadRequestErrorBody'
requestBody:
content:
application/json:
schema:
type: object
properties:
idempotency_key:
$ref: '#/components/schemas/IdempotencyKey'
payment:
$ref: '#/components/schemas/payments_CreatePaymentRequestPayment'
description: Data about the payment to create.
required:
- idempotency_key
- payment
tags:
- name: subpackage_payments
servers:
- url: https://api.cash.app/network/v1
description: Production
- url: https://sandbox.api.cash.app/network/v1
description: Sandbox
components:
schemas:
IdempotencyKey:
type: string
minLength: 1
maxLength: 64
description: >-
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-app-pay-partner-api/guides/technical-guides/api-fundamentals/idempotency).
title: IdempotencyKey
Currency:
type: string
enum:
- USD
description: >-
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.
Current values:
- `USD`: United States Dollar
title: Currency
Metadata:
type: object
additionalProperties:
type: string
description: >-
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 information (PII).
Min keys: `0`
Max keys: `50`
> Note: Nested keys are not supported.
title: Metadata
payments_PaymentEnrichmentsInitiationActor:
type: string
enum:
- CUSTOMER
- MERCHANT
description: |-
The party who initiated the payment.
- `CUSTOMER`
- `MERCHANT`
title: PaymentEnrichmentsInitiationActor
payments_PaymentEnrichmentsInitiation:
type: object
properties:
actor:
$ref: '#/components/schemas/payments_PaymentEnrichmentsInitiationActor'
description: |-
The party who initiated the payment.
- `CUSTOMER`
- `MERCHANT`
required:
- actor
description: If present, provides information about transaction initiation.
title: PaymentEnrichmentsInitiation
payments_PaymentEnrichmentsRestrictedCategoriesItem:
type: string
enum:
- ALCOHOL
- FINANCIAL_SERVICES
- CANNABIS
title: PaymentEnrichmentsRestrictedCategoriesItem
payments_PaymentEnrichments:
type: object
properties:
initiation:
$ref: '#/components/schemas/payments_PaymentEnrichmentsInitiation'
description: If present, provides information about transaction initiation.
recurring_series_id:
type: string
minLength: 1
maxLength: 1024
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/payments_PaymentEnrichmentsRestrictedCategoriesItem
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.
description: >-
Describes optional fields beyond core payment information to supplement
payment processing.
Enrichments provide additional context about a payment, which can
improve the overall payment experience including, but not limited to:
- Increased approval rates
- Enhanced transaction insights
- Better payment flows in Cash App
title: PaymentEnrichments
payments_CreatePaymentRequestPayment:
type: object
properties:
amount:
type: integer
minimum: 0
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
minLength: 1
maxLength: 128
description: |-
ID of the merchant to make the payment to.
Min length: `1`
Max length: `128`
grant_id:
type: string
minLength: 1
maxLength: 256
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
minLength: 1
maxLength: 1024
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/payments_PaymentEnrichments'
required:
- amount
- currency
- merchant_id
- grant_id
description: Data about the payment to create.
title: CreatePaymentRequestPayment
payments_PaymentStatus:
type: string
enum:
- AUTHORIZED
- CAPTURED
- VOIDED
- DECLINED
description: >-
The step of the payment processing lifecycle that this payment is
currently at.
- `AUTHORIZED`
- `CAPTURED`
- `VOIDED`
- `DECLINED`
title: PaymentStatus
ErrorCategory:
type: string
enum:
- API_ERROR
- AUTHENTICATION_ERROR
- BRAND_ERROR
- DISPUTE_ERROR
- MERCHANT_ERROR
- INVALID_REQUEST_ERROR
- PAYMENT_PROCESSING_ERROR
- RATE_LIMIT_ERROR
- WEBHOOK_ERROR
- API_KEY_ERROR
- GRANT_ERROR
description: The high-level reason the error occurred.
title: ErrorCategory
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.
For more information, see [Error Code
Reference](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference).
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
description: Represents an error encountered during a request to the API.
title: Error
feePlans_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.**
description: >-
A fee rate contains the components of a fee charged by Cash App to
partners for a given payment.
title: FeeRate
AuthorizationStatus:
type: string
enum:
- AUTHORIZED
- DECLINED
description: >-
The step of the authorization processing lifecycle that this
authorization is currently at.
Allowed values:
- AUTHORIZED
- DECLINED
title: AuthorizationStatus
Authorization:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 128
description: |-
Unique identifier for this authorization issued by Cash App.
Min length: 1 character
Max length: 128 characters
amount:
type: integer
minimum: 0
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
minLength: 1
maxLength: 128
description: ID of the payment associated with this authorization
previous_amount:
type: integer
minimum: 0
description: Total authorized amount before this authorization was requested
reference_id:
type: string
minLength: 1
maxLength: 1024
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
description: Represents an authorization update for a payment
title: Authorization
payments_Payment:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 128
description: |-
Unique identifier for this payment issued by Cash App.
Min length: `1`
Max length: `128`
amount:
type: integer
minimum: 1
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
minimum: 0
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
minimum: 0
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
minimum: 0
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
minimum: 0
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
minLength: 1
maxLength: 128
description: |-
ID of the customer that sent this payment.
Min length: `1`
Max length: `128`
merchant_id:
type: string
minLength: 1
maxLength: 128
description: |-
ID of the merchant that received this payment.
Min length: `1`
Max length: `128`
grant_id:
type: string
minLength: 1
maxLength: 256
description: |-
ID of the grant to used to create this payment.
Min length: `1`
Max length: `256`
status:
$ref: '#/components/schemas/payments_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
minLength: 1
maxLength: 1024
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/payments_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
minimum: 0
description: >-
The total fee amount that was charged to the merchant for processing
this payment.
fee_rate:
$ref: '#/components/schemas/feePlans_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
title: Payment
payments_CreatePaymentResponse:
type: object
properties:
payment:
$ref: '#/components/schemas/payments_Payment'
title: CreatePaymentResponse
CreatePaymentRequestBadRequestErrorBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
description: |-
A list of errors indicating why the request failed.
Min number of items: `1`
payment:
$ref: '#/components/schemas/payments_Payment'
required:
- errors
title: CreatePaymentRequestBadRequestErrorBody
```
**`Example`**
```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"
}
]
}
```