> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle payment issues

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

**Payment retry**: PayPal generates invoices for your customers' usage. As part of handling payment exceptions, you can retrieve the list of invoices with failed payment status and troubleshoot the issues. After you fix the problems, you can [retry payments](#retry-payment-for-an-invoice).

**Reconciliation and refunds**: Reconciliation involves comparing your billing records with actual usage data and payments to find discrepancies. After reconciliation, you may need to refund customers for billing adjustments. Common discrepancies include overcharges, duplicate charges, service interruptions, or pricing errors. To refund customers for these billing adjustments after invoice generation and payment processing, you can [create credit notes](#create-credit-notes). Credit notes can do the following:

* **Send refunds**: Returns money directly to the customer's payment method. Customers receive the refund immediately.
* **Add credits**: Returns credits to the customer's credit wallet. PayPal auto-creates this wallet. PayPal consumes these credits during future billing.

A single credit note can include both refund and credit amounts, giving you flexibility to split adjustments between immediate refunds and future account credits.

## Retry payment for an invoice

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a POST call to the `/v1/commerce/billing/invoices/{invoice_id}/retry_payment` endpoint.

**Path parameter**: `invoice_id` is the `id` returned in the <a href="/limited-release/usage-based-billing/meter-bill/generate-invoices#list-invoices" target="_blank" rel="noopener noreferrer">List invoices</a> response.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/invoices/9cf09b3f-9e52-434c-b3f4-3675739795fa/retry_payment' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```
</CodeGroup>

A successful call returns a `204 No Content` response.

## Create credit notes

A credit note is a billing adjustment document that reduces or reverses charges on an existing invoice. While an invoice charges customers, a credit note returns money or provides account credits. Create credit notes when you need to correct billing after invoices have been issued.

Each credit note references a specific invoice and can include both refund and credit amounts in a single adjustment.

<Warning>
  If refunds or credit amounts are not explicitly called out, the fee specified by the credit note is added as credits by default.
</Warning>

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a POST call to the `/v1/commerce/billing/credit-notes` endpoint. Include the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                         | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoice_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>     | Set to the `id` returned when you <a href="/limited-release/usage-based-billing/meter-bill/generate-invoices#list-invoices" target="_blank" rel="noopener noreferrer">listed the invoices</a>. |
| `reason`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                            | Set the reason for credit note creation.<br /><br /><b>Possible values:</b> `DUPLICATED_CHARGE`, `PRODUCT_UNSATISFACTORY`, `ORDER_CHANGE`, `ORDER_CANCELLATION`, `FRAUDULENT_CHARGE`, `OTHER`  |
| `description`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                       | Provide a description of the credit note for internal reference.                                                                                                                               |
| `credit_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                                     | Set the total amount to credit to the customer balance for future use. Only include `value` field (currency is inherited from invoice).                                                        |
| `refund_amount`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span>                                                                     | Set the total amount to refund to the customer immediately. Only include `value` field (currency is inherited from invoice).                                                                   |
| `items`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>           | Provide an array of credit note items specifying which fees to credit or refund. Minimum 1 item required.                                                                                      |
| `items[].fee_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set to the fee identifier from the original invoice.                                                                                                                                           |
| `items[].amount`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>object</span> | Set the amount for this credit note item. Only include `value` field.                                                                                                                          |

For information on all parameters, see <a href="/reference/api/rest/credit-notes/create-a-new-credit-note" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/credit-notes' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <ACCESS-TOKEN>' \
      -d '{
        "invoice_id": "a783c33f-acd4-4b34-b23c-77c0603e718e",
        "reason": "DUPLICATED_CHARGE",
        "description": "Refund for duplicated charge",
        "credit_amount": {
          "value": 25.00
        },
        "refund_amount": {
          "value": 25.00
        },
        "items": [
          {
            "fee_id": "6b873676-30ae-4ff9-846c-4b6ef4073e95",
            "amount": {
              "value": 50.00
            }
          }
        ]
      }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
        "id": "cadf054d-fac2-4e78-bb8c-0fbe2d536b54",
        "billing_entity_code": "agenticai",
        "sequential_id": 3,
        "number": "AGE-889C-202508-044-CN003",
        "invoice_id": "a783c33f-acd4-4b34-b23c-77c0603e718e",
        "invoice_number": "AGE-889C-202508-044",
        "issuing_date": "2025-08-07",
        "credit_status": "AVAILABLE",
        "refund_status": "PENDING",
        "reason": "DUPLICATED_CHARGE",
        "description": "Refund for duplicated charge",
        "total_amount": {
          "value": 50.00,
          "currency_code": "USD"
        },
        "credit_amount": {
          "value": 25.00,
          "currency_code": "USD"
        },
        "refund_amount": {
          "value": 25.00,
          "currency_code": "USD"
        },
        "balance_amount": {
          "value": 0.00,
          "currency_code": "USD"
        },
        "taxes_amount": {
          "value": 0.00,
          "currency_code": "USD"
        },
        "taxes_rate": 0.0,
        "sub_total_excluding_taxes_amount": {
          "value": 50.00,
          "currency_code": "USD"
        },
        "created_at": "2025-08-07T18:48:26Z",
        "updated_at": "2025-08-07T18:48:27Z",
        "items": [
          {
            "id": "859c48eb-ed78-4ecd-bc39-8b4ac0c07b63",
            "amount": {
              "value": 50.00,
              "currency_code": "USD"
            },
            "fee": {
              "id": "6b873676-30ae-4ff9-846c-4b6ef4073e95",
              "total_amount": {
                "value": 429.00,
                "currency_code": "USD"
              }
            }
          }
        ]
      }
  ```
</CodeGroup>

A successful call returns a `201 Created` response. The response includes the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                     | <span style={{textAlign: 'left', display: 'block'}}>Description</span>                             | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>            | Unique identifier for the credit note.                                                             | Use this `id` when <a href="/limited-release/usage-based-billing/manage-entities/manage-credit-notes#get-credit-note-details" target="_blank" rel="noopener noreferrer">getting credit note details</a> or <a href="/limited-release/usage-based-billing/manage-entities/manage-credit-notes#void-credit-notes" target="_blank" rel="noopener noreferrer">voiding the credit note</a>. |
| `credit_status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Status of the credit amount.<br /><br /><b>Possible values:</b> `AVAILABLE`, `CONSUMED`, `VOIDED`. | Use this `credit_status` to <a href="/limited-release/usage-based-billing/manage-entities/manage-credit-notes#list-credit-notes" target="_blank" rel="noopener noreferrer">filter credit notes</a>.                                                                                                                                                                                    |
| `refund_status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Status of the refund amount.<br /><br /><b>Possible values:</b> `PENDING`, `SUCCEEDED`, `FAILED`.  | Use this `refund_status` to <a href="/limited-release/usage-based-billing/manage-entities/manage-credit-notes#list-credit-notes" target="_blank" rel="noopener noreferrer">filter credit notes</a>.                                                                                                                                                                                    |

For information on all parameters, see <a href="/reference/api/rest/credit-notes/create-a-new-credit-note" target="_blank" rel="noopener noreferrer">API reference</a>.

## Manage credit notes

| Possible management action                                                                                                                                                                                                                    | Impact                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| <a href="/limited-release/usage-based-billing/manage-entities/manage-credit-notes#void-credit-notes" target="_blank" rel="noopener noreferrer">Void credit note</a>: Permanently delete a credit note, making it no longer available for use. | Changes status to `VOIDED` and prevents further credit application to pay charges. |