# Payments Use payments to process payments, for example, automate recurring payments, manage overpayments, and create refunds. For more information about payments, see Payments. ## List payments - [GET /v1/payments](https://developer.zuora.com/v1-api-reference/api/payments/get_retrieveallpayments.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all payments from all your customer accounts. ### Filtering You can use query parameters to restrict the data returned in the response. Each query parameter corresponds to one field in the response body. The unappliedAmount or any other query parameter does not support the less than() operators. If the value of a filterable field is string, you can set the corresponding query parameter to null when filtering. Then, you can get the response data with this field value being null. Examples: - /v1/payments?status=Processed - /v1/payments?currency=USD&status=Processed - /v1/payments?status=Processed&type=External&sort=+number ## Create a payment - [POST /v1/payments](https://developer.zuora.com/v1-api-reference/api/payments/post_createpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Creates a payment in the following scenarios: - A full or partial payment on an invoice or a debit memo - A full or partial payment on several invoices and debit memos - An unapplied payment in the following situations: - You do not know which customer account the payment belongs to. - You know which customer account the payment belongs to, but you do not know which invoice the payment is applied to. - You receive a payment from your customer that exceeds the balance on the invoice. - You receive a payment from your customer before the invoice has been created. - You intend to create a payment without any invoices or debit memos. - A standalone payment. If you only need to create and process an electronic payment in Zuora through a Zuora gateway integration but settle the payment outside of Zuora, you can create a standalone payment. For a standalone payment, you can specify a currency different from the payment currency in the customer account settings. When Standalone Payment is not enabled, the currency of the standalone payment can be different from the payment currency defined in the customer account settings if you have the Multiple Currencies feature enabled. If you do not know to which customer account the payment belongs, you can create a payment without specifying a customer account. When you create a payment, the total number of invoice items and debit memo items that the payment will apply to should be less than or equal to 15,000. For more information, see Create Payments and Create Payments Without Specifying Customer Accounts. ## Update a payment - [PUT /v1/payments/{paymentKey}](https://developer.zuora.com/v1-api-reference/api/payments/put_updatepayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Updates a payment. ## Delete a payment - [DELETE /v1/payments/{paymentKey}](https://developer.zuora.com/v1-api-reference/api/payments/delete_payment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Deletes a payment. Only payments with the Cancelled status can be deleted. If you have the Invoice Settlement feature enabled, overpayments applied to credit balance cannot be deleted. ## Retrieve a payment - [GET /v1/payments/{paymentKey}](https://developer.zuora.com/v1-api-reference/api/payments/get_payment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about one specific payment. ## Apply a payment - [PUT /v1/payments/{paymentKey}/apply](https://developer.zuora.com/v1-api-reference/api/payments/put_applypayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Applies an unapplied payment to invoices and debit memos. When you apply a payment, the total number of invoice items and debit memo items that the payment will apply to must be less than or equal to 15,000. If the limit is hit, you can follow the instructions: - If you want to apply one payment to multiple invoices or debit memos, decrease the number of invoices or debit memos in the request. - If you want to apply one payment to a single invoice or debit memo with a large volume of items, you have to specify invoice items in the request. The maximum number of invoice items that you can specify in the request is 1,000. For more information, see Apply Unapplied Payments to Invoices and Debit Memos. ## Cancel a payment - [PUT /v1/payments/{paymentKey}/cancel](https://developer.zuora.com/v1-api-reference/api/payments/put_cancelpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Cancels a payment. If you have the Invoice Settlement feature enabled, overpayments applied to credit balance cannot be cancelled. ## List all parts of a payment - [GET /v1/payments/{paymentKey}/parts](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentparts.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all parts of a payment. A payment can consist of an unapplied part, and several parts applied to invoices and debit memos. You can use this operation to get all the applied and unapplied portions of a payment. Note that a fully refunded payment does not contain any payment part. ## Retrieve a payment part - [GET /v1/payments/{paymentKey}/parts/{partid}](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentpart.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific payment part. A payment can consist of an unapplied part, and several parts applied to invoices and debit memos. A fully refunded payment does not contain any payment part. ## List all payment part items - [GET /v1/payments/{paymentKey}/parts/{partid}/item-parts](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentitemparts.md): Note: This operation is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about all items of a payment part. A payment part item is a single line item in a payment part. A payment part can consist of several different types of items. ## Retrieve a payment part item - [GET /v1/payments/{paymentKey}/parts/{partid}/item-parts/{itempartid}](https://developer.zuora.com/v1-api-reference/api/payments/get_paymentitempart.md): Note: This operation is only available if you have the Invoice Item Settlement feature enabled. Invoice Item Settlement must be used together with other Invoice Settlement features (Unapplied Payments, and Credit and Debit memos). If you wish to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Retrieves the information about a specific payment part item. A payment part item is a single line item in a payment part. A payment part can consist of several different types of items. ## Refund a payment - [POST /v1/payments/{paymentKey}/refunds](https://developer.zuora.com/v1-api-reference/api/payments/post_refundpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Refunds a full or partial unapplied payment to your customers. To refund applied payments, you must unapply the applied payments from the invoices or debit memos, and then refund the unapplied payments to customers. For more information on the payment refund use case, see Payment schedules use cases in the Knowledge Center. For more information, see Refund Payments. ## Refund a payment with auto-unapplying - [POST /v1/payments/{paymentKey}/refunds/unapply](https://developer.zuora.com/v1-api-reference/api/payments/post_refundpaymentwithautounapply.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Refunds a full or partial unapplied payment to your customers, without the need to unapply the payment first, followed by processing the refund. To refund applied payments, you can now leverage this API to unapply and refund the payment simultaneously. For more information on the payment refund use case, see Payment schedules use cases in the Knowledge Center. For more information, see Refund a payment with auto-unapplying. ## Transfer a payment - [PUT /v1/payments/{paymentKey}/transfer](https://developer.zuora.com/v1-api-reference/api/payments/put_transferpayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Transfers an unapplied payment. For more information, see Transfer Unapplied Payments. ## Unapply a payment - [PUT /v1/payments/{paymentKey}/unapply](https://developer.zuora.com/v1-api-reference/api/payments/put_unapplypayment.md): Note: This operation is only available if you have Invoice Settlement enabled. The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to enable Invoice Settlement, see Invoice Settlement Enablement and Checklist Guide for more information. Unapplies an applied payment from invoices and debit memos. When you unapply a payment, the total number of invoice items and debit memo items that the payment will unapply from must be less than or equal to 15,000. If the limit is hit, you can follow the instructions: - If you want to unapply one payment without specifying invoices or debit memos, you have to specify the invoices or debit memos in the request. - If you want to unapply one payment from multiple specified invoices or debit memos, decrease the number of invoices or debit memos in the request. - If you want to unapply one payment from a single invoice or debit memo with a large volume of items, you have to specify invoice items in the request. The maximum number of invoice items that you can specify in the request is 1,000. For more information, see Unapply Payments from Invoices and Debit Memos.