Handle payment issues

Limited Release

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. 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. 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 valid access token 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 List invoices response.

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>'

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.

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

Use a valid access token and make a POST call to the /v1/commerce/billing/credit-notes endpoint. Include the following parameters:

Parameter	Action
`invoice_id` Required, string	Set to the `id` returned when you listed the invoices.
`reason` string	Set the reason for credit note creation. Possible values: `DUPLICATED_CHARGE`, `PRODUCT_UNSATISFACTORY`, `ORDER_CHANGE`, `ORDER_CANCELLATION`, `FRAUDULENT_CHARGE`, `OTHER`
`description` string	Provide a description of the credit note for internal reference.
`credit_amount` object	Set the total amount to credit to the customer balance for future use. Only include `value` field (currency is inherited from invoice).
`refund_amount` object	Set the total amount to refund to the customer immediately. Only include `value` field (currency is inherited from invoice).
`items` Required, array	Provide an array of credit note items specifying which fees to credit or refund. Minimum 1 item required.
`items[].fee_id` Required, string	Set to the fee identifier from the original invoice.
`items[].amount` Required, object	Set the amount for this credit note item. Only include `value` field.

For information on all parameters, see API reference.

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
          }
        }
      ]
    }'

{
      "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"
            }
          }
        }
      ]
    }

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

Parameter	Description	Further action
`id` string	Unique identifier for the credit note.	Use this `id` when getting credit note details or voiding the credit note.
`credit_status` string	Status of the credit amount. Possible values: `AVAILABLE`, `CONSUMED`, `VOIDED`.	Use this `credit_status` to filter credit notes.
`refund_status` string	Status of the refund amount. Possible values: `PENDING`, `SUCCEEDED`, `FAILED`.	Use this `refund_status` to filter credit notes.

For information on all parameters, see API reference.

Manage credit notes

Possible management action	Impact
Void credit note: Permanently delete a credit note, making it no longer available for use.	Changes status to `VOIDED` and prevents further credit application to pay charges.

​Retry payment for an invoice

​Create credit notes

​Manage credit notes

Retry payment for an invoice

Create credit notes

Manage credit notes