For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
GuidesAPI Reference
GuidesAPI Reference
  • Network API
      • GETList payments
      • POSTCreate payment
      • GETRetrieve payment
      • POSTCreate incremental authorization
      • POSTCapture payment
      • POSTVoid payment
      • POSTVoid payment by idempotency key
      • Payment
      • Enrichments
      • POSTEvent: payment.status.updated
  • Customer Request API
  • Management API
LogoLogo
Network APIPayments

Create payment

POST
/payments
POST
/network/v1/payments
$curl -X POST https://api.cash.app/network/v1/payments \
>     -H "Accept: Accept" \
>     -H "X-Region: X-Region" \
>     -H "X-Signature: X-Signature" \
>     -H "User-Agent: User-Agent" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "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"
>    }
>  }
>}'
1{
2  "payment": {
3    "id": "PWC_4nn21zy6t0v2yhqg5bvhk7xkq",
4    "amount": 1500,
5    "net_amount": 1000,
6    "captured_amount": 1000,
7    "voided_amount": 0,
8    "refunded_amount": 100,
9    "currency": "USD",
10    "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
11    "merchant_id": "MMI_4vxs5egfk7hmta3qx2h6rp91x",
12    "grant_id": "GRG_221243dc6985a6819ff6950c1a21332f7bc4a46ebd49b5a7002908ab768e8e5ff7831e084d0d2c9d8d939793b55eff50",
13    "status": "AUTHORIZED",
14    "created_at": "2022-01-01T12:00:00Z",
15    "updated_at": "2022-01-05T12:00:00Z",
16    "capture_before": "2022-01-08T12:00:00Z",
17    "refund_ids": [
18      "PWCR_da1v3j4p3z15y47adpzzq0whj"
19    ],
20    "reference_id": "external-id",
21    "metadata": {},
22    "enrichments": {
23      "initiation": {
24        "actor": "CUSTOMER"
25      },
26      "recurring_series_id": "string",
27      "statement_descriptor": "string",
28      "restricted_categories": [
29        "ALCOHOL"
30      ]
31    },
32    "decline_errors": [
33      {
34        "category": "API_ERROR",
35        "code": "MISSING_REQUIRED_FIELD",
36        "detail": "Missing required parameter.",
37        "field": "field_a[2].field_b"
38      }
39    ],
40    "fee_amount": 1.1,
41    "fee_rate": {
42      "basis_points": 160,
43      "fixed_amount": 20
44    },
45    "authorization_updates": [
46      {
47        "id": "string",
48        "amount": 1,
49        "currency": "USD",
50        "status": "AUTHORIZED",
51        "created_at": "2024-01-15T09:30:00Z",
52        "payment_id": "string",
53        "previous_amount": 1,
54        "reference_id": "string",
55        "metadata": {},
56        "decline_errors": [
57          {
58            "category": "API_ERROR",
59            "code": "MISSING_REQUIRED_FIELD",
60            "detail": "Missing required parameter.",
61            "field": "field_a[2].field_b"
62          }
63        ]
64      }
65    ]
66  }
67}
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`
Was this page helpful?
Previous

Retrieve payment

Next
Built with

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

Headers

AcceptstringRequired
X-RegionstringRequired
X-SignaturestringRequired
User-AgentstringRequired

Request

idempotency_keystringRequired1-64 characters

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.

paymentobjectRequired
Data about the payment to create.

Response

Created
paymentobject

Errors

400
Bad Request Error