openapi: 3.2.0 info: title: Network Merchants API version: 1.0.0 servers: - url: https://api.cash.app/network/v1 description: Production - url: https://sandbox.api.cash.app/network/v1 description: Sandbox tags: - name: 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: - 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: application/json: schema: $ref: '#/components/schemas/List-merchantsRequestBadRequestError' 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: - 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: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 put: operationId: upsert-merchant summary: Upsert merchant description: "Creates or updates a merchant based on the merchant's `reference_id`.\n\nIf a merchant with a matching `reference_id` is found, \nit will be updated. If no matching merchant is found,\na new one will be created.\n\nThe HTTP response code (`200 OK` or `201 Created`) indicates\nwhether the resource was updated or created, respectively.\n\n\n\n `merchant_id` is the primary unique identifier for all Merchant APIs.\n Be cautious when using `reference_id` as a unique identifier.\n \n Merchants must have an `address` or `site_url` set.\n \n\n**This endpoint is not rate limited.**\n\nScopes: `MERCHANTS_WRITE`" tags: - 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: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 /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: - 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: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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: - 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: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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: Merchants_create-merchant_Response_201: type: object properties: merchant: $ref: '#/components/schemas/Merchant' required: - merchant title: Merchants_create-merchant_Response_201 Category: type: string description: The merchant category code associated with the entity. Values are from the [ISO-18245 specification](https://www.iso.org/standard/33365.html). title: Category List-merchantsRequestBadRequestError: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' required: - errors title: List-merchantsRequestBadRequestError 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 description: Details about the merchant to create or update. title: MerchantsPutRequestBodyContentApplicationJsonSchemaMerchant Country: type: string enum: - US description: '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 values: - `US`: United States of America' title: Country 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 description: A merchant represents a depository account when processing payments from Cash App customers. Merchants do not have direct access to Cash App, so processed payments are stored in this account until they are ready for settlement. title: Merchant 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 title: Merchants_list-merchants_Response_200 Merchants_update-merchant_Response_200: type: object properties: merchant: $ref: '#/components/schemas/Merchant' title: Merchants_update-merchant_Response_200 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' description: Details about the merchant to update. title: MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchant MerchantStatus: type: string enum: - ACTIVE - RISK_DISABLED - COMPLIANCE_DISABLED - CLIENT_DISABLED - PENDING 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.' title: MerchantStatus 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 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 MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchantStatus: type: string enum: - ACTIVE - CLIENT_DISABLED 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.' title: MerchantsMerchantIdPatchRequestBodyContentApplicationJsonSchemaMerchantStatus 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 IdempotencyKey: type: string 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 ErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' description: 'A list of errors that occurred while processing the request. Min number of items: `1`' required: - errors title: ErrorResponse Merchants_upsert-merchant_Response_200: type: object properties: merchant: $ref: '#/components/schemas/Merchant' required: - merchant title: Merchants_upsert-merchant_Response_200 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 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 description: Details about the merchant to create. title: MerchantsPostRequestBodyContentApplicationJsonSchemaMerchant 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. description: 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 processing payments for each channel. You can use the Fee Plans API to get all the fee information for each fee plan. title: MerchantFeePlans Merchants_retrieve-merchant_Response_200: type: object properties: merchant: $ref: '#/components/schemas/Merchant' required: - merchant title: Merchants_retrieve-merchant_Response_200 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 description: Where this entity is located title: Address