Billing Agreements API

Deprecation notice: The /v1/payments/billing-agreements endpoints are deprecated. Use the /v1/billing/subscriptions endpoints instead. For details, see Subscriptions Integration.
Use billing plans and billing agreements to create an agreement for a recurring PayPal or debit card payment for goods or services. To create an agreement, you reference an active billing plan from which the agreement inherits information. You also supply customer and payment information and, optionally, can override the referenced plan's merchant preferences and shipping fee and tax information. For more information, see Billing Plans and Agreements.
Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.
Note: The Billing Agreements API does not support the payee object.

Billing agreements (resource group)

Use the /billing-agreements resource to create, update, show details for, bill the balance for, cancel, reactivate, set the balance for, suspend, list transactions for, and execute agreements.

Create agreement

POST/v1/payments/billing-agreements
Creates a billing agreement. In the JSON request body, include an agreement object with the name, description, start date, ID of the plan on which to base the agreement, and customer and shipping address information.

Request body

  • description

    string

    required

    The agreement description.

    Maximum length: 128.

  • name

    string

    required

    The agreement name.

    Maximum length: 128.

  • payer

    object

    required

    The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

  • plan

    object

    required

    The ID of the plan on which this agreement is based.

  • start_date

    string

    required

    The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

    The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

  • agreement_details

    object

    The agreement details.

  • id

    string

    The PayPal-generated ID for the resource.

    Maximum length: 128.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

  • override_charge_models

    array (contains the override_charge_model object)

    An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

  • override_merchant_preferences

    object

    The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

  • shipping_address

    object

    The shipping address for a payment. Must be provided if it differs from the default address.

  • state

    enum

    The state of the agreement. Value is:

    • Pending. The agreement awaits initial payment completion.
    • Active. The agreement is active and payments are scheduled.
    • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
    • Cancelled. The agreement is cancelled and payments are not scheduled.
    • Expired. The agreement is expired and no more payments remain to be scheduled.

    Possible values: Pending,Active,Suspended,Cancelled,Expired.

    Maximum length: 128.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Override Agreement",
  "description": "PayPal payment agreement that overrides merchant preferences and shipping fee and tax information.",
  "start_date": "2017-12-22T09:13:49Z",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "payer@example.com"
    }
  },
  "plan": {
    "id": "P-1WJ68935LL406420PUTENA2I"
  },
  "shipping_address": {
    "line1": "Hotel Staybridge",
    "line2": "Crooke Street",
    "city": "San Jose",
    "state": "CA",
    "postal_code": "95112",
    "country_code": "US"
  },
  "override_merchant_preferences": {
    "setup_fee": {
      "value": "3",
      "currency": "GBP"
    },
    "return_url": "https://example.com/",
    "cancel_url": "https://example.com/cancel",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE",
    "max_fail_attempts": "11"
  },
  "override_charge_models": [
    {
      "charge_id": "CHM-8373958130821962WUTENA2Q",
      "amount": {
        "value": "1",
        "currency": "GBP"
      }
    }
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing agreement details including a billing agreement id and redirect links to get the buyer's approval.
  • agreement_details

    object

    The agreement details.

  • description

    string

    The agreement description.

    Maximum length: 128.

  • id

    string

    The PayPal-generated ID for the resource.

    Read only.

    Maximum length: 128.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

  • name

    string

    The agreement name.

    Maximum length: 128.

  • override_charge_models

    array (contains the override_charge_model object)

    An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

  • override_merchant_preferences

    object

    The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

  • payer

    object

    The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

  • plan

    object

    The plan that can be used to create an agreement.

  • shipping_address

    object

    The shipping address of the agreement, which must be provided if it differs from the default address.

  • start_date

    string

    The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

    The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

  • state

    enum

    The state of the agreement. Value is:

    • Pending. The agreement awaits initial payment completion.
    • Active. The agreement is active and payments are scheduled.
    • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
    • Cancelled. The agreement is cancelled and payments are not scheduled.
    • Expired. The agreement is expired and no more payments remain to be scheduled.

    Read only.

    Possible values: Pending,Active,Suspended,Cancelled,Expired.

    Maximum length: 128.

Sample Response

{
  "name": "Override Agreement",
  "description": "Agreement that overrides merchant preferences and charge models",
  "payer": {
    "payment_method": "paypal",
    "payer_info": {
      "email": "payer@example.com"
    }
  },
  "plan": {
    "id": "P-1WJ68935LL406420PUTENA2I",
    "state": "ACTIVE",
    "name": "Fast Speed Plan",
    "description": "Vanilla plan",
    "type": "INFINITE",
    "payment_definitions": [
      {
        "id": "PD-9WG6983719571780GUTENA2I",
        "name": "Regular payment definition",
        "type": "REGULAR",
        "frequency": "DAY",
        "amount": {
          "currency": "GBP",
          "value": "10"
        },
        "charge_models": [
          {
            "id": "CHM-8373958130821962WUTENA2Q",
            "type": "SHIPPING",
            "amount": {
              "currency": "GBP",
              "value": "1"
            }
          },
          {
            "id": "CHM-2937144979861454NUTENA2Q",
            "type": "TAX",
            "amount": {
              "currency": "GBP",
              "value": "2"
            }
          }
        ],
        "cycles": "0",
        "frequency_interval": "1"
      },
      {
        "id": "PD-89M493313S710490TUTENA2Q",
        "name": "Trial payment definition",
        "type": "TRIAL",
        "frequency": "MONTH",
        "amount": {
          "currency": "GBP",
          "value": "100"
        },
        "charge_models": [
          {
            "id": "CHM-78K47820SS4923826UTENA2Q",
            "type": "SHIPPING",
            "amount": {
              "currency": "GBP",
              "value": "10"
            }
          },
          {
            "id": "CHM-9M366179U7339472RUTENA2Q",
            "type": "TAX",
            "amount": {
              "currency": "GBP",
              "value": "12"
            }
          }
        ],
        "cycles": "5",
        "frequency_interval": "2"
      }
    ],
    "merchant_preferences": {
      "setup_fee": {
        "currency": "GBP",
        "value": "3"
      },
      "max_fail_attempts": "11",
      "return_url": "https://example.com/",
      "cancel_url": "https://example.com/cancel",
      "auto_bill_amount": "YES",
      "initial_fail_amount_action": "CONTINUE"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-83C745436S346813F",
      "rel": "approval_url",
      "method": "REDIRECT"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/EC-83C745436S346813F/agreement-execute",
      "rel": "execute",
      "method": "POST"
    }
  ],
  "start_date": "2017-12-22T09:13:49Z"
}

Update agreement

PATCH/v1/payments/billing-agreements/{agreement_id}
Updates details of a billing agreement, by ID. The details include the description, shipping address, start date, and so on.
Note: For the PayPal payment method, you cannot update the start_date after the agreement is created.

Path parameters

  • agreement_id

    string

    required

    The ID of the agreement to update.

Request body

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

Sample Request

curl -v -X PATCH https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
    "op": "replace",
    "path": "/",
    "value": {
      "description": "Updated description.",
      "start_date": "2017-12-22T09:13:49Z",
      "shipping_address": {
        "line1": "Hotel Blue Diamond",
        "line2": "Church Street",
        "city": "San Jose",
        "state": "CA",
        "postal_code": "95112",
        "country_code": "US"
      }
    }
  }
]'

Response

A successful request returns the HTTP 200 OK status code with no JSON response body.

    Sample Response

    200 OK

    Show agreement details

    GET/v1/payments/billing-agreements/{agreement_id}
    Shows details for a billing agreement, by ID.

    Path parameters

    • agreement_id

      string

      required

      The ID of the agreement for which to show details.

    Sample Request

    curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-5D3XDN2D5FH1 \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Access-Token"

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.
    • agreement_details

      object

      The agreement details.

    • description

      string

      The agreement description.

      Maximum length: 128.

    • id

      string

      The PayPal-generated ID for the resource.

      Read only.

      Maximum length: 128.

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

      Read only.

    • override_charge_models

      array (contains the override_charge_model object)

      An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

    • override_merchant_preferences

      object

      The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

    • payer

      object

      The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

    • plan

      object

      The plan that can be used to create an agreement.

    • shipping_address

      object

      The shipping address for a payment. Must be provided if it differs from the default address.

    • start_date

      string

      The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

      The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

    • state

      enum

      The state of the agreement. Value is:

      • Pending. The agreement awaits initial payment completion.
      • Active. The agreement is active and payments are scheduled.
      • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
      • Cancelled. The agreement is cancelled and payments are not scheduled.
      • Expired. The agreement is expired and no payments remain to be scheduled.

      Read only.

      Possible values: Pending,Active,Suspended,Cancelled,Expired.

      Maximum length: 128.

    Sample Response

    {
      "id": "I-1TJ3GAGG82Y9",
      "state": "Active",
      "description": "Monthly agreement with free trial payment definition.",
      "payer": {
        "payment_method": "paypal",
        "status": "unverified",
        "payer_info": {
          "email": "johndoe@example.com",
          "first_name": "John",
          "last_name": "Doe",
          "payer_id": "NEW8A85AK4ET4",
          "shipping_address": {
            "recipient_name": "John Doe",
            "line1": "751235 Stout Drive",
            "line2": "0976249 Elizabeth Court",
            "city": "Quimby",
            "state": "IA",
            "postal_code": "51049",
            "country_code": "US"
          }
        }
      },
      "plan": {
        "name": "Plan with Regular and Trial Payment Definitions",
        "description": "Plan with regular and trial payment definitions.",
        "type": "FIXED",
        "payment_definitions": [
          {
            "name": "Trial payment definition",
            "type": "TRIAL",
            "frequency": "MONTH",
            "amount": {
              "value": "0.00",
              "currency": "USD"
            },
            "cycles": "2",
            "charge_models": [
              {
                "type": "TAX",
                "amount": {
                  "value": "0.00",
                  "currency": "USD"
                }
              },
              {
                "type": "SHIPPING",
                "amount": {
                  "value": "0.00",
                  "currency": "USD"
                }
              }
            ],
            "frequency_interval": "1"
          },
          {
            "name": "Regular payment definition",
            "type": "REGULAR",
            "frequency": "MONTH",
            "amount": {
              "value": "5.99",
              "currency": "USD"
            },
            "cycles": "10",
            "charge_models": [
              {
                "type": "TAX",
                "amount": {
                  "value": "0.29",
                  "currency": "USD"
                }
              },
              {
                "type": "SHIPPING",
                "amount": {
                  "value": "0.20",
                  "currency": "USD"
                }
              }
            ],
            "frequency_interval": "1"
          }
        ],
        "merchant_preferences": {
          "setup_fee": {
            "value": "0.40",
            "currency": "USD"
          },
          "return_url": "https://example.com",
          "cancel_url": "https://example.com/cancel",
          "max_fail_attempts": "2",
          "auto_bill_amount": "YES"
        },
        "links": [],
        "currency_code": "USD"
      },
      "start_date": "2016-12-23T08:00:00Z",
      "shipping_address": {
        "recipient_name": "John Doe",
        "line1": "751235 Stout Drive",
        "line2": "0976249 Elizabeth Court",
        "city": "Quimby",
        "state": "IA",
        "postal_code": "51049",
        "country_code": "US"
      },
      "agreement_details": {
        "outstanding_balance": {
          "currency": "USD",
          "value": "0.00"
        },
        "cycles_remaining": "2",
        "cycles_completed": "0",
        "next_billing_date": "2017-01-23T08:00:00Z",
        "last_payment_date": "2016-12-23T08:00:00Z",
        "last_payment_amount": {
          "currency": "USD",
          "value": "0.40"
        },
        "final_payment_date": "2017-09-23T08:00:00Z",
        "failed_payment_count": "0"
      },
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend",
          "rel": "suspend",
          "method": "POST"
        },
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate",
          "rel": "re_activate",
          "method": "POST"
        },
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel",
          "rel": "cancel",
          "method": "POST"
        },
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance",
          "rel": "self",
          "method": "POST"
        },
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance",
          "rel": "self",
          "method": "POST"
        }
      ]
    }

    Bill agreement balance

    POST/v1/payments/billing-agreements/{agreement_id}/bill-balance
    Bills the balance for an agreement, by ID. In the JSON request body, include an optional note that describes the reason for the billing action and the agreement amount and currency.

    Path parameters

    • agreement_id

      string

      required

      The ID of the agreement for which to bill the balance.

    Request body

    • note

      string

      The reason for the agreement state change.

      Maximum length: 128.

    Sample Request

    curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer Access-Token" \
    -d '{
      "note": "Billing balance amount."
    }'

    Response

    A successful request returns the HTTP 204 No Content status code with no JSON response body.

      Sample Response

      204 No Content

      Cancel agreement

      POST/v1/payments/billing-agreements/{agreement_id}/cancel
      Cancels a billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor object with an optional note that describes the reason for the cancellation and the agreement amount and currency.

      Path parameters

      • agreement_id

        string

        required

        The ID of the agreement to cancel.

      Request body

      • note

        string

        The reason for the agreement state change.

        Maximum length: 128.

      Sample Request

      curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer Access-Token" \
      -d '{
        "note": "Canceling the profile."
      }'

      Response

      A successful request returns the HTTP 204 No Content status code with no JSON response body.

        Sample Response

        204 No Content

        Reactivate agreement

        POST/v1/payments/billing-agreements/{agreement_id}/re-activate
        Reactivates a suspended billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor object with with a note that describes the reason for the reactivation and the agreement amount and currency.

        Path parameters

        • agreement_id

          string

          required

          The ID of the agreement to reactivate.

        Request body

        • note

          string

          The reason for the agreement state change.

          Maximum length: 128.

        Sample Request

        curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer Access-Token" \
        -d '{
          "note": "Reactivating the profile."
        }'

        Response

        A successful request returns the HTTP 204 No Content status code with no JSON response body.

          Sample Response

          204 No Content

          Set agreement balance

          POST/v1/payments/billing-agreements/{agreement_id}/set-balance
          Sets the balance for an agreement, by ID. In the JSON request body, specify the balance currency type and value.

          Path parameters

          • agreement_id

            string

            required

            The ID of the agreement for which to set a balance.

          Request body

          • currency

            string

            required

            The three-character ISO-4217 currency code that identifies the currency.

            Minimum length: 3.

            Maximum length: 3.

          • value

            string

            required

            The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

            Maximum length: 32.

            Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

          Sample Request

          curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer Access-Token" \
          -d '{
            "value": "100",
            "currency": "USD"
          }'

          Response

          A successful request returns the HTTP 204 No Content status code with no JSON response body.

            Sample Response

            204 No Content

            Suspend agreement

            POST/v1/payments/billing-agreements/{agreement_id}/suspend
            Suspends a billing agreement, by ID.

            Path parameters

            • agreement_id

              string

              required

              The ID of the agreement to suspend.

            Request body

            • note

              string

              The reason for the agreement state change.

              Maximum length: 128.

            Sample Request

            curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer Access-Token" \
            -d '{
              "note": "Suspending the profile."
            }'

            Response

            A successful request returns the HTTP 204 No Content status code with no JSON response body.

              Sample Response

              204 No Content

              List agreement transactions

              GET/v1/payments/billing-agreements/{agreement_id}/transactions
              Lists transactions for an agreement, by ID. To filter the transactions that appear in the response, specify the optional start and end date query parameters.

              Query parameters

              • end_date

                string

                The end date of the range of transactions to list.

              • start_date

                string

                The start date of the range of transactions to list.

              Path parameters

              • agreement_id

                string

                required

                The ID of the agreement for which to list transactions.

              Sample Request

              curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/transactions?start_date=2017-06-15&end_date=2017-06-17 \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer Access-Token"

              Response

              A successful request returns the HTTP 200 OK status code and a JSON response body that lists transactions with details.
              • agreement_transaction_list

                array (contains the agreement_transaction object)

                An array of agreement transactions.

              Sample Response

              {
                "agreement_transaction_list": [
                  {
                    "transaction_id": "I-V8SSE9WLJGY6",
                    "status": "Completed",
                    "transaction_type": "Recurring Payment",
                    "amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "fee_amount": {
                      "value": "1",
                      "currency": "USD"
                    },
                    "net_amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "payer_email": "",
                    "payer_name": " ",
                    "time_stamp": "2017-06-16T13:46:53Z",
                    "time_zone": "GMT"
                  },
                  {
                    "transaction_id": "I-V8SSE9WLJGY6",
                    "status": "Denied",
                    "transaction_type": "Recurring Payment",
                    "amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "fee_amount": {
                      "value": "1",
                      "currency": "USD"
                    },
                    "net_amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "payer_email": "",
                    "payer_name": " ",
                    "time_stamp": "2017-06-16T13:52:26Z",
                    "time_zone": "GMT"
                  },
                  {
                    "transaction_id": "I-V8SSE9WLJGY6",
                    "status": "Pending",
                    "transaction_type": "Recurring Payment",
                    "amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "fee_amount": {
                      "value": "1",
                      "currency": "USD"
                    },
                    "net_amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "payer_email": "",
                    "payer_name": " ",
                    "time_stamp": "2017-06-16T14:00:23Z",
                    "time_zone": "GMT"
                  },
                  {
                    "transaction_id": "I-V8SSE9WLJGY6",
                    "status": "Denied",
                    "transaction_type": "Recurring Payment",
                    "amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "fee_amount": {
                      "value": "1",
                      "currency": "USD"
                    },
                    "net_amount": {
                      "value": "100",
                      "currency": "USD"
                    },
                    "payer_email": "",
                    "payer_name": " ",
                    "time_stamp": "2017-06-16T14:02:54Z",
                    "time_zone": "GMT"
                  }
                ]
              }

              Execute agreement

              POST/v1/payments/billing-agreements/{payment_token}/agreement-execute
              Executes a billing agreement, by ID, after customer approval.

              Path parameters

              • payment_token

                string

                required

                The ID of the agreement to execute.

              Sample Request

              curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer Access-Token"

              Response

              A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.
              • agreement_details

                object

                The agreement details.

              • description

                string

                The agreement description.

                Maximum length: 128.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • override_charge_models

                array (contains the override_charge_model object)

                An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

              • override_merchant_preferences

                object

                The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

              • payer

                object

                The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

              • plan

                object

                The plan that can be used to create an agreement.

              • shipping_address

                object

                The shipping address for a payment. Must be provided if it differs from the default address.

              • start_date

                string

                The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

                The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

              • state

                enum

                The state of the agreement. Value is:

                • Pending. The agreement awaits initial payment completion.
                • Active. The agreement is active and payments are scheduled.
                • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
                • Cancelled. The agreement is cancelled and payments are not scheduled.
                • Expired. The agreement is expired and no payments remain to be scheduled.

                Read only.

                Possible values: Pending,Active,Suspended,Cancelled,Expired.

                Maximum length: 128.

              Sample Response

              {
                "id": "I-1TJ3GAGG82Y9",
                "state": "Active",
                "description": "Monthly agreement with free trial payment definition.",
                "payer": {
                  "payment_method": "paypal",
                  "status": "unverified",
                  "payer_info": {
                    "email": "johndoe@example.com",
                    "first_name": "John",
                    "last_name": "Doe",
                    "payer_id": "NEW8A85AK4ET4",
                    "shipping_address": {
                      "recipient_name": "John Doe",
                      "line1": "751235 Stout Drive",
                      "line2": "0976249 Elizabeth Court",
                      "city": "Quimby",
                      "state": "IA",
                      "postal_code": "51049",
                      "country_code": "US"
                    }
                  }
                },
                "plan": {
                  "name": "Plan with Regular and Trial Payment Definitions",
                  "description": "Plan with regular and trial payment definitions.",
                  "type": "FIXED",
                  "payment_definitions": [
                    {
                      "name": "Trial payment definition",
                      "type": "TRIAL",
                      "frequency": "MONTH",
                      "amount": {
                        "value": "0.00",
                        "currency": "USD"
                      },
                      "cycles": "2",
                      "charge_models": [
                        {
                          "type": "TAX",
                          "amount": {
                            "value": "0.00",
                            "currency": "USD"
                          }
                        },
                        {
                          "type": "SHIPPING",
                          "amount": {
                            "value": "0.00",
                            "currency": "USD"
                          }
                        }
                      ],
                      "frequency_interval": "1"
                    },
                    {
                      "name": "Regular payment definition",
                      "type": "REGULAR",
                      "frequency": "MONTH",
                      "amount": {
                        "value": "5.99",
                        "currency": "USD"
                      },
                      "cycles": "10",
                      "charge_models": [
                        {
                          "type": "TAX",
                          "amount": {
                            "value": "0.29",
                            "currency": "USD"
                          }
                        },
                        {
                          "type": "SHIPPING",
                          "amount": {
                            "value": "0.20",
                            "currency": "USD"
                          }
                        }
                      ],
                      "frequency_interval": "1"
                    }
                  ],
                  "merchant_preferences": {
                    "setup_fee": {
                      "value": "0.40",
                      "currency": "USD"
                    },
                    "return_url": "https://example.com",
                    "cancel_url": "https://example.com/cancel",
                    "max_fail_attempts": "2",
                    "auto_bill_amount": "YES"
                  },
                  "links": [],
                  "currency_code": "USD"
                },
                "start_date": "2016-12-23T08:00:00Z",
                "shipping_address": {
                  "recipient_name": "John Doe",
                  "line1": "751235 Stout Drive",
                  "line2": "0976249 Elizabeth Court",
                  "city": "Quimby",
                  "state": "IA",
                  "postal_code": "51049",
                  "country_code": "US"
                },
                "agreement_details": {
                  "outstanding_balance": {
                    "value": "0.00",
                    "currency": "USD"
                  },
                  "cycles_remaining": "2",
                  "cycles_completed": "0",
                  "next_billing_date": "2017-01-23T08:00:00Z",
                  "last_payment_date": "2016-12-23T08:00:00Z",
                  "last_payment_amount": {
                    "value": "0.40",
                    "currency": "USD"
                  },
                  "final_payment_date": "2017-09-23T08:00:00Z",
                  "failed_payment_count": "0"
                },
                "links": [
                  {
                    "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9",
                    "rel": "self",
                    "method": "GET"
                  }
                ]
              }

              Common object definitions

              address

              • city

                string

                required

                The city name.

              • country_code

                string

                required

                The two-character ISO 3166-1 code that identifies the country or region.

                Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

                Minimum length: 2.

                Maximum length: 2.

                Pattern: ^([A-Z]{2}|C2)$.

              • line1

                string

                required

                The first line of the address. For example, number or street.

              • line2

                string

                The second line of the address. For example, suite or apartment number.

              • postal_code

                string

                The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

              • state

                string

                The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.

              address_postal_code_validation

              • address_postal_code_validation

              agreement

              • description

                string

                required

                The agreement description.

                Maximum length: 128.

              • payer

                object

                required

                The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

              • plan

                object

                required

                The plan that can be used to create an agreement.

              • start_date

                string

                required

                The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

                The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

              • agreement_details

                object

                The agreement details.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • override_charge_models

                array (contains the override_charge_model object)

                An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

              • override_merchant_preferences

                object

                The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

              • shipping_address

                object

                The shipping address for a payment. Must be provided if it differs from the default address.

              • state

                enum

                The state of the agreement. Value is:

                • Pending. The agreement awaits initial payment completion.
                • Active. The agreement is active and payments are scheduled.
                • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
                • Cancelled. The agreement is cancelled and payments are not scheduled.
                • Expired. The agreement is expired and no payments remain to be scheduled.

                Read only.

                Possible values: Pending,Active,Suspended,Cancelled,Expired.

                Maximum length: 128.

              agreement_details

              • cycles_completed

                string

                The number of payment cycles completed for this agreement.

              • cycles_remaining

                string

                The number of payment cycles remaining for this agreement.

              • failed_payment_count

                string

                The total number of failed payments for this agreement.

              • final_payment_date

                string

                The final payment date and time for this agreement, in Internet date and time format. For example, 2017-09-23T08:00:00Z.

              • last_payment_amount

                object

                The currency and amount of the last payment amount for this agreement.

              • last_payment_date

                string

                The last payment date and time for this agreement, in Internet date and time format. For example, 2016-12-23T08:00:00Z.

              • next_billing_date

                string

                The next billing date and time for this agreement, in Internet date and time format. For example, 2017-01-23T08:00:00Z.

              • outstanding_balance

                object

                The currency and amount of the outstanding balance for this agreement.

              agreement_state_descriptor

              • note

                string

                The reason for the agreement state change.

                Maximum length: 128.

              agreement_transaction

              • amount

                object

                required

                The currency and amount of the transaction.

              • fee_amount

                object

                required

                The currency and amount of the transaction fee.

              • net_amount

                object

                required

                The currency and amount of the transaction net amount.

              • payer_email

                string

                The email ID of the customer.

                Read only.

              • payer_name

                string

                The business name of the customer.

                Read only.

              • status

                enum

                The current status of the transaction. Value is:

                • Completed. The transaction is complete and the money has been transferred to the payee.
                • Partially_Refunded. A part of the transaction amount has been refunded to the payer.
                • Pending. The transaction is pending settlement.
                • Refunded. The transaction amount has been refunded to the payer.
                • Denied. The transaction has been denied.

                Read only.

                Possible values: Completed,Partially_Refunded,Pending,Refunded,Denied.

              • time_stamp

                string

                The date and time when the transaction occurred, in Internet date and time format.

                Read only.

              • time_zone

                string

                The time zone of the update_time field.

                Read only.

              • transaction_id

                string

                The ID of the transaction.

                Read only.

              • transaction_type

                string

                The type of transaction. Typically, Recurring Payment.

                Read only.

              agreement_transactions

              • agreement_transaction_list

                array (contains the agreement_transaction object)

                An array of agreement transactions.

              bank_account

              • account_number

                string

                required

                The account number in international bank account number (IBAN) format or basic bank account number (BBAN) format. The maximum length for the IBAN format is 34 characters. The maximum length for the BBAN format is 17 characters.

                Maximum length: 34.

              • account_number_type

                enum

                required

                The type of bank account number. A valid value is basic bank account number (BBAN) or international bank account number (IBAN). For more information, see International Bank Account Number.

                Possible values: BBAN,IBAN.

              • account_name

                string

                A customer-designated account name.

                Maximum length: 64.

              • account_type

                enum

                The bank account type.

                Possible values: CHECKING,SAVINGS.

              • auth_capture_timestamp

                string

                The date and time when the authorization was captured, in Internet date and time format. Use this parameter if you must capture the user authorization due to any privacy requirements.

              • auth_type

                enum

                The authorization type, which indicates how the check was obtained from the customer if a check is the source of information.

                Possible values: CCD,PPD,TEL,POP,ARC,RCK,WEB.

              • bank_name

                string

                The bank name.

                Maximum length: 64.

              • billing_address

                object

                The billing address.

              • birth_date

                string

                The account holder's birth date.

              • check_type

                enum

                The check type when the information was obtained from the facilitator or merchant.

                Possible values: PERSONAL,COMPANY.

              • confirmation_status

                enum

                The confirmation status of a bank account.

                Read only.

                Possible values: UNCONFIRMED,CONFIRMED.

              • country_code

                string

                The two-letter country code of the bank.

              • create_time

                string

                The date and time when the bank account was created, in Internet date and time format.

                Read only.

              • external_customer_id

                string

                The facilitator-generated ID for the customer who owns this bank account. Required when you create or use a vaulted funding instrument.

                Maximum length: 256.

              • first_name

                string

                The account holder's first name.

                Maximum length: 64.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • last_name

                string

                The account holder's last name.

                Maximum length: 64.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • merchant_id

                string

                The facilitator-generated ID for the merchant for whom the bank account was vaulted that can be used to restrict usage of the bank account to the merchant.

                Maximum length: 256.

              • payer_id

                string

                Deprecated. Instead, use the external_customer_id parameter.

              • routing_number

                string

                The routing transit number, or bank code, of the bank. Typically, you specify this value for domestic use only. International bank account numbers (IBAN) include the bank code. For more information, see Bank code.

                Maximum length: 34.

              • state

                enum

                The state of this funding instrument.

                Read only.

                Possible values: ACTIVE,INACTIVE,DELETED.

              • update_time

                string

                The date and time when the bank account was last updated, in Internet date and time format.

                Read only.

              • valid_until

                string

                The date and time after which the bank account can no longer be used to fund a payment, in Internet date and time format.

                Read only.

              charge_model

              • amount

                object

                required

                The currency and amount for this charge model.

              • type

                enum

                required

                The charge model type.

                Possible values: TAX,SHIPPING.

                Maximum length: 20.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              country_code

              • country_code

                string

                The two-character ISO 3166-1 code that identifies the country or region.

                Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

                Minimum length: 2.

                Maximum length: 2.

                Pattern: ^([A-Z]{2}|C2)$.

              create_agreement_request

              • description

                string

                required

                The agreement description.

                Maximum length: 128.

              • name

                string

                required

                The agreement name.

                Maximum length: 128.

              • payer

                object

                required

                The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

              • plan

                object

                required

                The ID of the plan on which this agreement is based.

              • start_date

                string

                required

                The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

                The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

              • agreement_details

                object

                The agreement details.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • override_charge_models

                array (contains the override_charge_model object)

                An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

              • override_merchant_preferences

                object

                The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

              • shipping_address

                object

                The shipping address for a payment. Must be provided if it differs from the default address.

              • state

                enum

                The state of the agreement. Value is:

                • Pending. The agreement awaits initial payment completion.
                • Active. The agreement is active and payments are scheduled.
                • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
                • Cancelled. The agreement is cancelled and payments are not scheduled.
                • Expired. The agreement is expired and no more payments remain to be scheduled.

                Read only.

                Possible values: Pending,Active,Suspended,Cancelled,Expired.

                Maximum length: 128.

              create_agreement_response

              • description

                string

                required

                The agreement description.

                Maximum length: 128.

              • name

                string

                required

                The agreement name.

                Maximum length: 128.

              • payer

                object

                required

                The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.

              • plan

                object

                required

                The plan that can be used to create an agreement.

              • start_date

                string

                required

                The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.

                The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.

              • agreement_details

                object

                The agreement details.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • override_charge_models

                array (contains the override_charge_model object)

                An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.

              • override_merchant_preferences

                object

                The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

              • shipping_address

                object

                The shipping address of the agreement, which must be provided if it differs from the default address.

              • state

                enum

                The state of the agreement. Value is:

                • Pending. The agreement awaits initial payment completion.
                • Active. The agreement is active and payments are scheduled.
                • Suspended. The agreement is suspended and payments are not scheduled until the agreement is reactivated.
                • Cancelled. The agreement is cancelled and payments are not scheduled.
                • Expired. The agreement is expired and no more payments remain to be scheduled.

                Read only.

                Possible values: Pending,Active,Suspended,Cancelled,Expired.

                Maximum length: 128.

              credit_card

              • expire_month

                integer

                required

                The two-digit card expiry month, in MM format. Value is from 01 to 12.

              • expire_year

                integer

                required

                The four-digit card expiry year, in YYYY format.

              • number

                string

                required

                The card number.

              • type

                string

                required

                The card type. For example, Visa, MasterCard, and so on.

              • billing_address

                object

                The billing address associated with this card.

              • cvv2

                integer

                The card validation code. Supported only when making a payment but not when saving a credit card for future use.

              • external_customer_id

                string

                The facilitator-provided ID of the customer who owns this bank account. Required when storing a funding instrument or using a stored funding instrument in the PayPal vault.

                Maximum length: 256.

              • first_name

                string

                The first name of the card holder.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

              • last_name

                string

                The last name of the card holder.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • state

                enum

                The state of the funding instrument.

                Read only.

                Possible values: expired,ok.

              • valid_until

                string

                The date and time when the credit card becomes unusable from the vault, in Internet date and time format. The valid_until parameter is not the same as the expiration month and year. The expiration month and year might be later than the valid_until date. For example, the card expires in November 2019 but the valid_until date is October 17th, 2019.

                Read only.

              currency

              • currency

                string

                required

                The three-character ISO-4217 currency code that identifies the currency.

                Minimum length: 3.

                Maximum length: 3.

              • value

                string

                required

                The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

                Maximum length: 32.

                Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$.

              currency_code

              error

              • information_link

                string

                required

                The URI to detailed information related to this error for the developer.

                Read only.

              • message

                string

                required

                The message that describes the error.

                Read only.

              • name

                string

                required

                The human-readable, unique name of the error.

                Read only.

              • debug_id

                string

                The PayPal internal ID. Used for correlation purposes.

                Read only.

              • details

                array (contains the error_details object)

                An array of additional details for the error.

                Read only.

              error_details

              • field

                string

                required

                The name of the field that caused the error.

              • issue

                string

                required

                The reason for the error.

              funding_instrument

              • credit_card

                object

                A credit card that can be used to fund a payment.

              merchant_preferences

              • cancel_url

                string

                required

                The URL to which the customer is redirected if they cancel the agreement.

                Maximum length: 1000.

              • return_url

                string

                required

                The URL to which the customer is redirected if they accept the agreement.

                Maximum length: 1000.

              • accepted_payment_type

                string

                The payment types that are accepted for this agreement. Read-only and reserved for future use.

                Read only.

              • auto_bill_amount

                enum

                Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is:

                • NO. PayPal does not automatically bill the customer the outstanding balance. Default is NO.
                • YES. PayPal automatically bills the customer the outstanding balance.

                Possible values: YES,NO.

              • char_set

                string

                The character set for this agreement. Read-only and reserved for future use.

                Read only.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • initial_fail_amount_action

                enum

                The action if the customer's initial payment fails. Value is:

                • CONTINUE. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.
                • CANCEL. PayPal creates the agreement but sets its state to pending until the initial payment clears. When the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is cancelled.
                Note: Initial payment failures will not increment the max_fail_attempt counter as initial payments are not considered regularly recurring payments.

                Possible values: CONTINUE,CANCEL.

              • max_fail_attempts

                string

                The maximum number of allowed failed payment attempts. Default is 0, which allows infinite failed payment attempts.

              • setup_fee

                object

                The currency and amount of the fee to set up the agreement. Default is 0.

              override_charge_model

              • amount

                object

                required

                The updated amount and currency for this charge model.

              • charge_id

                string

                required

                The ID of the charge model.

              patch

              • op

                enum

                required

                The operation.

                The possible values are:

                • add. Depending on the target location reference, completes one of these functions:
                  • The target location is an array index. Inserts a new value into the array at the specified index.
                  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
                  • The target location is an object parameter that does exist. Replaces that parameter's value.
                  The value parameter defines the value to add. For more information, see 4.1. add.
                • remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
                • replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
                • move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
                • copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.
                • test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
                  TypeConsidered equal if both values
                  stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
                  numbersAre numerically equal.
                  arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
                  objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
                  literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
                  For more information, see 4.6. test.
              • from

                string

                The JSON Pointer to the target document location from which to move the value. Required for the move operation.

              • path

                string

                The JSON Pointer to the target document location at which to complete the operation.

              • value

                number,integer,string,boolean,null,array,object

                The value to apply. The remove operation does not require a value.

              patch_request

              • patch_request

                array (contains the patch object)

                An array of JSON patch objects to apply partial updates to resources.

              payer

              • payment_method

                enum

                required

                The payment method.

                Possible values: bank,paypal.

              • funding_instruments

                array (contains the funding_instrument object)

                An array of funding instruments.

              • funding_option_id

                string

                The ID of the customer-selected funding option for the payment. Value is funding_instruments or funding_option_id.

                Read only.

              • payer_info

                object

                The payer information.

              payer_info

              • billing_address

                object

                The payer's billing address.

              • email

                string

                The payer's email address.

              • first_name

                string

                The payer's first name.

                Read only.

              • last_name

                string

                The payer's last name.

                Read only.

              • payer_id

                string

                The PayPal-assigned ID for the payer.

                Read only.

              • shipping_address

                object

                The shipping address for a payment. Must be provided if it differs from the default address.

              payment_definition

              • amount

                object

                required

                The currency and amount to charge at the end of each payment cycle for this definition.

              • cycles

                string

                required

                The number of payment cycles in this definition. For infinite plans with a regular payment definition, set cycles to 0.

              • frequency

                enum

                required

                The frequency of the payment in this definition.

                Note: You can specify the frequency value in any case. For example, you can specify the frequency of the payment as WEEK, Week, or week.

                The possible values are:

                • WEEK. The payment is weekly.
                • DAY. The payment is daily.
                • YEAR. The payment is yearly.
                • MONTH. The payment is monthly.
              • frequency_interval

                string

                required

                The interval at which the customer is charged. Value cannot be greater than 12 months.

              • name

                string

                required

                The payment definition name.

                Maximum length: 128.

              • type

                enum

                required

                The payment definition type.

                Possible values: TRIAL,REGULAR.

              • charge_models

                array (contains the charge_model object)

                An array of shipping fee and tax information for this definition.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              plan

              • description

                string

                required

                The plan description.

                Maximum length: 128.

              • name

                string

                required

                The plan name.

                Maximum length: 128.

              • type

                enum

                required

                The plan type.

                Possible values: FIXED,INFINITE.

                Maximum length: 20.

              • create_time

                string

                The date and time when the plan was created, in Internet date and time format.

                Read only.

              • currency_code

                string

                The currency code for the plan.

                Read only.

              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              • links

                array (contains the link_description object)

                An array of request-related HATEOAS links.

                Read only.

              • merchant_preferences

                object

                The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

              • payment_definitions

                array (contains the payment_definition object)

                An array of payment definitions for this plan.

              • state

                enum

                The status of the plan.

                Read only.

                Possible values: CREATED,ACTIVE,INACTIVE,DELETED.

              • terms

                array (contains the terms object)

                An array of terms for this plan.

                Read only.

              • update_time

                string

                The date and time when this plan was updated, in Internet date and time format.

                Read only.

              plan

              • id

                string

                The ID of the plan.

                Maximum length: 128.

              shipping_address

              • default_address

                boolean

                The default shipping address of the payer.

              • recipient_name

                string

                The name of the recipient at this address.

              • city

                string

                required

                The city name.

              • country_code

                string

                required

                The two-character ISO 3166-1 code that identifies the country or region.

                Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

                Minimum length: 2.

                Maximum length: 2.

                Pattern: ^([A-Z]{2}|C2)$.

              • line1

                string

                required

                The first line of the address. For example, number or street.

              • line2

                string

                The second line of the address. For example, suite or apartment number.

              • postal_code

                string

                The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

              • state

                string

                The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.

              terms

              • amount_range

                object

                required

                The amount range for this term.

              • buyer_editable

                string

                required

                Indicates whether the customer can edit the amount in this term.

              • max_billing_amount

                object

                required

                The currency and amount of the maximum billing amount associated with this term.

              • occurrences

                string

                required

                The number of times that money can be pulled during this term.

              • type

                enum

                required

                The term type.

                The possible values are:

                • MONTHLY. The term is monthly.
                • WEEKLY. The term is weekly.
                • YEARLY. The term is yearly.
              • id

                string

                The PayPal-generated ID for the resource.

                Read only.

                Maximum length: 128.

              Additional API information

              Error messages

              In addition to the common HTTP status codes that the REST APIs return, the Billing Agreements API can return the following errors.

              • ACCOUNT_RESTRICTED

                This transaction cannot be processed. Contact PayPal Customer Service.

                This account is restricted.

              • ADDRESS_INVALID

                The user address is not valid.

                The address is not valid.

              • BA_TOKEN

                Invalid request - see details.

                Invalid agreement ID. The ID is the B-XXXXXXXXXXXXXXXXXX type.

              • BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE

                The billed amount should be less than the outstanding balance.

                The billed amount is too large.

              • BUSADD_STATE_UNSUPPORTED

                This transaction cannot be processed.

                The country listed for your business address is not currently supported.

              • CALL_FAILED_PAYMENT

                Payment is failing.

                The payment is failing.

              • CANNOT_FIND_PROFILE_DESC

                The profile description is not valid.

                Provide a valid agreement description.

              • CANNOT_MIX_CURRENCIES

                The currency code is not valid. All currency codes much match.

                Use same currency code for all amount objects.

              • CANT_INCREASE_OUTSTANDING_AMOUNT

                Cannot increase the delinquent amount.

                You cannot increase the outstanding amount for the bill.

              • CC_STATUS_INVALID

                Profile is not active.

                The state of the profile is not active.

              • CC_TYPE_NOT_SUPPORTED

                The credit card type is not supported.

                Use another type of credit card.

              • DPRP_DISABLED

                DPRP is disabled for this merchant.

                To enable Direct Payment Recurring Payments (DPRP), enable Pro mode for your merchant sandbox account. Go to Sandbox accounts and click the Business account in the Type column. Click Profile and enable the Pro features on this business sandbox account.

              • DUPLICATE_REQUEST_ID

                The value of PayPal-Request-Id header has already been used.

                Use a unique PayPal-Request-Id header value to resend the request.

              • EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED

                Business error.

                The buyer has not approved this token.

              • EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN

                Business error.

                A session validation error occurred. The session does not belong to the merchant.

              • FEATURE_DISABLED

                This transaction cannot be processed.

                This feature is disabled.

              • FEATURE_NOT_AVAILABLE

                Because the recurring payments feature is not currently available, you must try again later.

                This feature is not available.

              • GATEWAY_DECLINE_CVV2

                This transaction cannot be processed. Enter a valid credit card verification number.

                The verification number is not valid.

              • INTERNAL_ERROR

                Internal Error.

                Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

              • INTERNAL_SERVICE_ERROR

                An internal service error has occurred.

                Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

              • INVALID_AMOUNT

                The bill amount must be greater than 0.

                Specify a valid amount.

              • INVALID_ARGS

                Invalid argument. The description field or custom field is empty and the status is active.

                Pass correct arguments in the description field and make sure that the status is active.

              • INVALID_CC_NUMBER

                This transaction cannot be processed. Enter a valid credit card number and type.

                The credit card number and type are not valid.

              • INVALID_CURRENCY

                This transaction cannot be processed due to an unsupported currency.

                This currency is not supported.

              • INVALID_ID_PASSED

                Business error.

                The ID is invalid ID.

              • INVALID_PROFILE_ACTION

                The action value is not valid.

                Enter a valid action.

              • INVALID_PROFILE_ID

                The profile ID is not valid.

                Enter a valid profile ID.

              • INVALID_PROFILE_STATUS

                The profile status must be one of (A)ctive, (C)ancelled, or e(X)pired.

                Enter a valid profile status.

              • INVALID_SECURITY_CTX

                Business error.

                The security context is invalid.

              • INVALID_STATUS_TO_CANCEL

                The status is not valid for the suspend action. The profile must be active.

                The agreement must be active before you can suspend it.

              • INVALID_STATUS_TO_REACTIVATE

                The activation type is not valid.

                Pass a valid activation type.

              • INVALID_STATUS_TO_SUSPEND

                Invalid profile status for reactivate action. Profile must be suspended.

                To complete this action, you must first suspend the agreement.

              • INVALID_TOKEN

                The token is missing or is invalid.

                Enter a valid token.

              • MALFORMED_REQUEST

                The request JSON is not well formed.

                Review the JSON request.

              • MERCHANT_ACCOUNT_DENIED

                Merchant account is denied.

                The merchant account is denied.

              • MERCHANT_COUNTRY_NOT_SUPPORTED

                The merchant country is not supported.

                This country is not supported.

              • MERCHANT_ID_NOT_AUTHORIZED

                Business error.

                The merchant ID not authorized to get the details.

              • MISSING_CVV2

                This transaction cannot be processed without a credit card verification number.

                Enter the credit card verification number.

              • OUTSTANDING_PAYMENT_ALREADY_SCHEDULED

                Another outstanding payment is scheduled.

                Another payment is already scheduled.

              • PAYER_ACCOUNT_DENIED

                The payer's account is denied.

                The payer's account is denied.

              • PAYER_COUNTRY_NOT_SUPPORTED

                The payer's country is currently not supported.

                This country is not supported.

              • PAYMENT_METHOD

                Invalid request - see details.

                Invalid payment method. Valid value is PAYPAL.

              • PLAN_TYPE

                Invalid request - see details.

                Invalid type mentioned. Valid values are MERCHANT_INITIATED_BILLING or CHANNEL_INITIATED_BILLING.

              • PROCESSOR_DECLINE_INVALID_CC_COUNTRY

                This credit card was issued from an unsupported country.

                This country is not supported.

              • RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS

                The recurring payment was scheduled within 24 hours, so the bill outstanding amount cannot be processed.

                This bill outstanding amount cannot be processed.

              • REQUIRED_SCOPE_MISSING

                Access token does not have required scope.

                Obtain user consent by using the correct scope for this request type.

              • REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED

                Authorization error.

                This facilitator account is not permitted for Channel Initiated Billing.

              • REFUSED_MARK_REF_TXN_NOT_ENABLED

                Authorization error.

                This merchant account is not permitted to create Merchant Initiated Billing Agreement.

              • RT_AGREEMENT_ALREADY_CANCELED

                Business error.

                Failed Request: Agreement is already cancelled / Invalid agreement state.

              • RT_INVALID_AGREEMENT_ID

                Business error.

                No matching record found.

              • SET_BALANCE_INVALID_CURRENCY_CODE

                Invalid currency for delinquent amount.

                Specify a valid currency in the bill-balance call.

              • SHIPPING_ADDRESS_NOT_IN_RESIDENCE_COUNTRY

                This transaction cannot be processed. The shipping country is not allowed by the buyer's country of residence.

                The shipping country is not supported.

              • SHP_INVALID_COUNTRY_CODE

                This transaction cannot be processed. Enter a valid country code in the shipping address.

                Enter a valid country code.

              • START_DATE_INVALID_FORMAT

                The subscription start date must be valid.

                Specify a valid start date in Internet date and time format. The start date must be greater than the current date.

              • STATUS_INVALID

                The profile status is not valid for the reactivate action. The status must be active.

                Make sure that the status is active.

              • SUBSCRIPTION_UNMAPPED_ERROR

                An internal error occurred.

                An internal error occurred.

              • TIME_TO_UPDATE_CLOSE_TO_BILLING_DATE

                The time of the update is too close to the billing date.

                You cannot make an update this close to the billing date.

              • TOKEN_NOT_FOUND

                Internal error.

                Invalid BA-Token Identifier. Valid token has the BA-XXXXXXXXXXXXXXXXX format.

              • UNAUTHORIZED_AGREEMENT_REQUEST

                You do not have permission to create this agreement.

                You are not authorized to create this agreement.

              • USR_BILLING_AGRMNT_NOT_ACTIVE

                This transaction cannot be processed due to an invalid merchant configuration.

                The merchant configuration is not valid.

              • VALIDATION_ERROR

                Invalid request - see details.

                Your request has a validation error.

              • WALLET_TOO_MANY_ATTEMPTS

                You have exceeded the maximum number of payment attempts for this token.

                Create a token and use it to create an agreement.