openapi: 3.2.0 info: title: Billing Agreements description:
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.
version: "1.1" x-serviceName: subscriptionmgmtserv x-publicDocsPath: billing-agreements externalDocs: url: /docs/subscriptions/integrate/ servers: - url: https://api-m.sandbox.paypal.com description: PayPal API Sandbox tags: - name: billing-agreements description: 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. paths: /billing-agreements: post: tags: - billing-agreements summary: Create agreement description: 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. operationId: billing-agreements.post requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/create_agreement_request" - type: object examples: - name: Direct Payment Recurring Profile description: Credit card payment start_date: 2016-12-23T08:00:00Z plan: id: P-2PL786081D358645F6NWEKFQ payer: payment_method: credit_card payer_info: email: johndoe@example.com funding_instruments: - credit_card: type: visa number: "4417119664863864" expire_month: 12 expire_year: 2021 cvv2: 111 billing_address: line1: "065769 Holcomb Bridge Road #141" line2: "5713 E Dimond Boulevard #B9" city: Wichita state: KS postal_code: "67202" country_code: US required: false responses: "201": description: 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. content: application/json: schema: $ref: "#/components/schemas/create_agreement_response" default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: C# link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingAgreementWithCreditCard.aspx.cs - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/create.js - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/create.py x-codegen-request-body-name: agreement /billing-agreements/{payment_token}/agreement-execute: post: tags: - billing-agreements summary: Execute agreement description: Executes a billing agreement, by ID, after customer approval. operationId: billing-agreements.agreement-execute parameters: - name: payment_token in: path description: The ID of the agreement to execute. required: true schema: type: string responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing agreement details. content: application/json: schema: $ref: "#/components/schemas/agreement" default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: C# link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingAgreementCreateAndExecute.aspx.cs - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/execute.js - language: PHP link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/ExecuteAgreement.php - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/execute.py /billing-agreements/{agreement_id}: get: tags: - billing-agreements summary: Show agreement details description: Shows details for a billing agreement, by ID. operationId: billing-agreements.get parameters: - name: agreement_id in: path description: The ID of the agreement for which to show details. required: true schema: type: string responses: "200": description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing agreement details. content: application/json: schema: $ref: "#/components/schemas/agreement" default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: C# link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingAgreementGet.aspx.cs - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/get.js - language: PHP link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/GetBillingAgreement.php - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/get.py patch: tags: - billing-agreements summary: Update agreement description: 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.
operationId: billing-agreements.patch parameters: - name: agreement_id in: path description: The ID of the agreement to update. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/patch_request" - type: object examples: - - 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 required: false responses: "200": description: A successful request returns the HTTP `200 OK` status code with no JSON response body. content: {} default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/update.js - language: PHP link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/UpdateBillingAgreement.php - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/replace.py x-codegen-request-body-name: patch_request /billing-agreements/{agreement_id}/suspend: post: tags: - billing-agreements summary: Suspend agreement description: Suspends a billing agreement, by ID. operationId: billing-agreements.suspend parameters: - name: agreement_id in: path description: The ID of the agreement to suspend. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/agreement_state_descriptor" - type: object examples: - note: Suspending the profile. required: false responses: "204": description: A successful request returns the HTTP `204 No Content` status code with no JSON response body. content: {} default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/suspend_and_re_activate.js - language: PHP link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/SuspendBillingAgreement.php - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/suspend_and_re_activate.py x-codegen-request-body-name: agreement_state_descriptor /billing-agreements/{agreement_id}/re-activate: post: tags: - billing-agreements summary: Reactivate agreement description: 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. operationId: billing-agreements.re-activate parameters: - name: agreement_id in: path description: The ID of the agreement to reactivate. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/agreement_state_descriptor" - type: object examples: - note: Reactivating the profile. required: false responses: "204": description: A successful request returns the HTTP `204 No Content` status code with no JSON response body. content: {} default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/suspend_and_re_activate.js - language: PHP link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/ReactivateBillingAgreement.php - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/suspend_and_re_activate.py x-codegen-request-body-name: agreement_state_descriptor /billing-agreements/{agreement_id}/cancel: post: tags: - billing-agreements summary: Cancel agreement description: 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. operationId: billing-agreements.cancel parameters: - name: agreement_id in: path description: The ID of the agreement to cancel. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/agreement_state_descriptor" - type: object examples: - note: Canceling the profile. required: false responses: "204": description: A successful request returns the HTTP `204 No Content` status code with no JSON response body. content: {} default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/cancel.js - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/cancel.py x-codegen-request-body-name: agreement_state_descriptor /billing-agreements/{agreement_id}/bill-balance: post: tags: - billing-agreements summary: Bill agreement balance description: 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. operationId: billing-agreements.bill-balance parameters: - name: agreement_id in: path description: The ID of the agreement for which to bill the balance. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/agreement_state_descriptor" - type: object examples: - note: Billing balance amount. required: false responses: "204": description: A successful request returns the HTTP `204 No Content` status code with no JSON response body. content: {} default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/set_balance_and_bill_balance.js - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/set_balance_and_bill_balance.py x-codegen-request-body-name: agreement_state_descriptor /billing-agreements/{agreement_id}/set-balance: post: tags: - billing-agreements summary: Set agreement balance description: Sets the balance for an agreement, by ID. In the JSON request body, specify the balance currency type and value. operationId: billing-agreements.set-balance parameters: - name: agreement_id in: path description: The ID of the agreement for which to set a balance. required: true schema: type: string requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/currency" - type: object examples: - value: "100" currency: USD required: false responses: "204": description: A successful request returns the HTTP `204 No Content` status code with no JSON response body. content: {} default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/set_balance_and_bill_balance.js - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/set_balance_and_bill_balance.py x-codegen-request-body-name: currency /billing-agreements/{agreement_id}/transactions: get: tags: - billing-agreements summary: List agreement transactions description: 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. operationId: billing-agreements.transactions parameters: - name: agreement_id in: path description: The ID of the agreement for which to list transactions. required: true schema: type: string - name: start_date in: query description: The start date of the range of transactions to list. schema: type: string - name: end_date in: query description: The end date of the range of transactions to list. schema: type: string responses: "200": description: A successful request returns the HTTP ` 200 OK` status code and a JSON response body that lists transactions with details. content: application/json: schema: $ref: "#/components/schemas/agreement_transactions" default: description: The error response. content: application/json: schema: $ref: "#/components/schemas/error" security: - Oauth2: - https://uri.paypal.com/services/subscriptions x-slo: response_time_95th_percentile: 0 error_rate: 0.1 x-visibility: extent: EXTERNAL x-publicSDKSamples: - language: C# link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingAgreementListTransactions.aspx.cs - language: Node link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_agreements/search_transactions.js - language: PHP link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/SearchBillingTransactions.php - language: Python link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_agreements/search_transactions.py components: schemas: create_agreement_response: title: Create Agreement Response required: - description - name - payer - plan - start_date type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true state: maxLength: 128 type: string description: The state of the agreement. Value is: readOnly: true enum: - Pending - Active - Suspended - Cancelled - Expired name: maxLength: 128 type: string description: The agreement name. description: maxLength: 128 type: string description: The agreement description. start_date: type: string description: The date and time when this agreement begins, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). 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. format: date-time agreement_details: $ref: "#/components/schemas/agreement_details" payer: $ref: "#/components/schemas/payer" override_merchant_preferences: $ref: "#/components/schemas/merchant_preferences" override_charge_models: type: array description: 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. items: type: object allOf: - type: object x-publicDocsSchemaName: override_charge_model - $ref: "#/components/schemas/override_charge_model" plan: $ref: "#/components/schemas/plan" links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: type: object allOf: - $ref: "#/components/schemas/link_description" - type: object x-publicDocsSchemaName: link_description - type: object readOnly: true shipping_address: type: object allOf: - type: object description: The shipping address of the agreement, which must be provided if it differs from the default address. - $ref: "#/components/schemas/address" - type: object x-publicDocsSchemaName: address description: The billing agreement information. x-visibility: extent: EXTERNAL error: title: Error required: - information_link - message - name type: object properties: name: type: string description: The human-readable, unique name of the error. readOnly: true debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. readOnly: true message: type: string description: The message that describes the error. readOnly: true information_link: type: string description: The URI to detailed information related to this error for the developer. readOnly: true details: type: array description: An array of additional details for the error. readOnly: true items: type: object allOf: - $ref: "#/components/schemas/error_details" - type: object x-publicDocsSchemaName: error_details description: The error information. create_agreement_request: title: Create Agreement Request required: - description - name - payer - plan - start_date type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true state: maxLength: 128 type: string description: The state of the agreement. Value is: readOnly: true enum: - Pending - Active - Suspended - Cancelled - Expired name: maxLength: 128 type: string description: The agreement name. description: maxLength: 128 type: string description: The agreement description. start_date: type: string description: The date and time when this agreement begins, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). 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. format: date-time agreement_details: $ref: "#/components/schemas/agreement_details" payer: $ref: "#/components/schemas/payer" override_merchant_preferences: $ref: "#/components/schemas/merchant_preferences" override_charge_models: type: array description: 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. items: type: object allOf: - type: object x-publicDocsSchemaName: override_charge_model - $ref: "#/components/schemas/override_charge_model" plan: title: Plan type: object properties: id: maxLength: 128 type: string description: The ID of the plan. description: The ID of the plan on which this agreement is based. links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: type: object allOf: - $ref: "#/components/schemas/link_description" - type: object x-publicDocsSchemaName: link_description - type: object readOnly: true shipping_address: type: object allOf: - $ref: "#/components/schemas/shipping_address" - type: object x-visibility: extent: EXTERNAL description: The billing agreement information. x-visibility: extent: EXTERNAL agreement: title: Agreement required: - description - payer - plan - start_date type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true state: maxLength: 128 type: string description: The state of the agreement. Value is: readOnly: true enum: - Pending - Active - Suspended - Cancelled - Expired description: maxLength: 128 type: string description: The agreement description. start_date: type: string description: The date and time when this agreement begins, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). 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. format: date-time agreement_details: $ref: "#/components/schemas/agreement_details" payer: $ref: "#/components/schemas/payer" override_merchant_preferences: $ref: "#/components/schemas/merchant_preferences" override_charge_models: type: array description: 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. items: type: object allOf: - type: object x-publicDocsSchemaName: override_charge_model - $ref: "#/components/schemas/override_charge_model" plan: $ref: "#/components/schemas/plan" links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: type: object allOf: - $ref: "#/components/schemas/link_description" - type: object x-publicDocsSchemaName: link_description - type: object readOnly: true shipping_address: type: object allOf: - $ref: "#/components/schemas/shipping_address" - type: object x-visibility: extent: EXTERNAL description: The billing agreement information. x-visibility: extent: EXTERNAL patch_request: title: Patch Request type: array description: An array of JSON patch objects to apply partial updates to resources. items: type: object allOf: - $ref: "#/components/schemas/patch" - type: object x-publicDocsSchemaName: patch agreement_state_descriptor: title: Agreement State Descriptor type: object properties: note: maxLength: 128 type: string description: The reason for the agreement state change. description: The description of the current state of an agreement. x-visibility: extent: EXTERNAL currency: title: Currency required: - currency - value type: object properties: value: maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ type: string description: 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](https://www.iso.org/iso-4217-currency-codes.html). currency: type: object allOf: - $ref: "#/components/schemas/currency_code" - type: object x-publicDocsSchemaName: currency_code description: The currency and amount for a transaction. x-visibility: extent: EXTERNAL agreement_transactions: title: Agreement Transactions type: object properties: agreement_transaction_list: type: array description: An array of agreement transactions. items: type: object allOf: - $ref: "#/components/schemas/agreement_transaction" - type: object x-publicDocsSchemaName: agreement_transaction description: An array of agreement transactions. x-visibility: extent: EXTERNAL agreement_details: title: Agreement Details type: object properties: cycles_remaining: type: string description: The number of payment cycles remaining for this agreement. cycles_completed: type: string description: The number of payment cycles completed for this agreement. next_billing_date: type: string description: The next billing date and time for this agreement, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2017-01-23T08:00:00Z`. last_payment_date: type: string description: The last payment date and time for this agreement, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2016-12-23T08:00:00Z`. final_payment_date: type: string description: The final payment date and time for this agreement, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2017-09-23T08:00:00Z`. failed_payment_count: type: string description: The total number of failed payments for this agreement. outstanding_balance: type: object allOf: - type: object description: The currency and amount of the outstanding balance for this agreement. - $ref: "#/components/schemas/currency" - type: object x-publicDocsSchemaName: currency last_payment_amount: type: object allOf: - type: object description: The currency and amount of the last payment amount for this agreement. - $ref: "#/components/schemas/currency" - type: object x-publicDocsSchemaName: currency description: The agreement details. x-visibility: extent: EXTERNAL payer: title: Payer required: - payment_method type: object properties: payment_method: type: string description: The payment method. enum: - bank - paypal x-enumVisibility: bank: extent: EXTERNAL description: A debit card payment. paypal: extent: EXTERNAL description: A PayPal payment. funding_instruments: type: array description: An array of funding instruments. items: type: object allOf: - type: object x-publicDocsSchemaName: funding_instrument - $ref: "#/components/schemas/funding_instrument" funding_option_id: type: string description: The ID of the customer-selected funding option for the payment. Value is `funding_instruments` or `funding_option_id`. readOnly: true payer_info: $ref: "#/components/schemas/payer_info" description: The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. x-visibility: extent: EXTERNAL address: title: Simple Postal Address (Coarse-Grained) required: - city - country_code - line1 type: object properties: line1: type: string description: The first line of the address. For example, number or street. line2: type: string description: The second line of the address. For example, suite or apartment number. city: type: string description: The city name. state: type: string description: "The [code](/docs/integration/direct/rest/state-codes/) for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: [Argentina](/docs/integration/direct/rest/state-codes/#argentina), [Brazil](/docs/integration/direct/rest/state-codes/#brazil), [Canada](/docs/integration/direct/rest/state-codes/#canada), [China](/docs/integration/direct/rest/state-codes/#china), [India](/docs/integration/direct/rest/state-codes/#india), [Italy](/docs/integration/direct/rest/state-codes/#italy), [Japan](/docs/integration/direct/rest/state-codes/#japan), [Mexico](/docs/integration/direct/rest/state-codes/#mexico), [Thailand](/docs/integration/direct/rest/state-codes/#thailand), or [United States](/docs/integration/direct/rest/state-codes/#usa). Maximum length is 40 single-byte characters." country_code: $ref: "#/components/schemas/country_code" postal_code: type: string description: The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). description: A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone. x-pattern: $ref: "#/components/schemas/address_postal_code_validation" merchant_preferences: title: Merchant Preferences required: - cancel_url - return_url type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true cancel_url: maxLength: 1000 type: string description: The URL to which the customer is redirected if they cancel the agreement. format: uri return_url: maxLength: 1000 type: string description: The URL to which the customer is redirected if they accept the agreement. format: uri max_fail_attempts: type: string description: The maximum number of allowed failed payment attempts. Default is `0`, which allows infinite failed payment attempts. auto_bill_amount: type: string description: 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: enum: - YES - NO initial_fail_amount_action: type: string description: The action if the customer's initial payment fails. Value is:
Note: Initial payment failures will not increment the max_fail_attempt counter as initial payments are not considered regularly recurring payments.
default: CONTINUE enum: - CONTINUE - CANCEL accepted_payment_type: type: string description: The payment types that are accepted for this agreement. Read-only and reserved for future use. readOnly: true char_set: type: string description: The character set for this agreement. Read-only and reserved for future use. readOnly: true setup_fee: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount of the fee to set up the agreement. Default is `0`. description: 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. x-visibility: extent: EXTERNAL override_charge_model: title: Override Charge Model required: - amount - charge_id type: object properties: charge_id: type: string description: The ID of the charge model. amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The updated amount and currency for this charge model. - type: object x-publicDocsSchemaName: currency description: The charge model that overrides default charge information during agreement creation. x-visibility: extent: EXTERNAL plan: title: Plan required: - description - name - type type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true name: maxLength: 128 type: string description: The plan name. description: maxLength: 128 type: string description: The plan description. type: maxLength: 20 type: string description: The plan type. enum: - FIXED - INFINITE state: type: string description: The status of the plan. readOnly: true enum: - CREATED - ACTIVE - INACTIVE - DELETED create_time: type: string description: The date and time when the plan was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true update_time: type: string description: The date and time when this plan was updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true payment_definitions: type: array description: An array of payment definitions for this plan. items: type: object allOf: - $ref: "#/components/schemas/payment_definition" - type: object x-publicDocsSchemaName: payment_definition - type: object description: The payment definition, which defines a regular or trial payment.
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.
terms: type: array description: An array of terms for this plan. readOnly: true items: type: object allOf: - type: object x-publicDocsSchemaName: term - $ref: "#/components/schemas/terms" merchant_preferences: $ref: "#/components/schemas/merchant_preferences" links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: type: object allOf: - $ref: "#/components/schemas/link_description" - type: object x-publicDocsSchemaName: link_description - type: object readOnly: true currency_code: type: object allOf: - type: object description: The currency code for the plan. - $ref: "#/components/schemas/currency_code" - type: object readOnly: true - type: object x-visibility: extent: EXTERNAL description: The plan that can be used to create an agreement. x-visibility: extent: EXTERNAL x-links: - rel: self href: "{plan-id}" method: GET link_description: title: Link Description required: - href - rel type: object properties: href: type: string description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. x-visibility: extent: EXTERNAL rel: type: string description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). x-visibility: extent: EXTERNAL method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH x-visibility: extent: EXTERNAL description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information. currency_code: title: currency_code maxLength: 3 minLength: 3 type: string description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. format: ppaas_common_currency_code_v2 funding_instrument: title: Funding Instrument type: object properties: credit_card: type: object allOf: - $ref: "#/components/schemas/credit_card" - type: object description: A credit card that can be used to fund a payment. description: The customer's funding instrument that can be used to fund a payment. x-visibility: extent: EXTERNAL payer_info: title: Payer Information type: object properties: email: type: string description: The payer's email address. format: email first_name: type: string description: The payer's first name. readOnly: true last_name: type: string description: The payer's last name. readOnly: true payer_id: type: string description: The PayPal-assigned ID for the payer. readOnly: true shipping_address: type: object allOf: - $ref: "#/components/schemas/shipping_address" - type: object x-visibility: extent: EXTERNAL billing_address: type: object allOf: - $ref: "#/components/schemas/address" - type: object description: The payer's billing address. - type: object x-publicDocsSchemaName: address description: The payer information. x-visibility: extent: EXTERNAL credit_card: title: Credit Card required: - expire_month - expire_year - number - type type: object properties: id: type: string description: The PayPal-generated ID for the resource. readOnly: true number: type: string description: The card number. type: type: string description: The card type. For example, Visa, MasterCard, and so on. expire_month: type: integer description: The two-digit card expiry month, in `MM` format. Value is from `01` to `12`. expire_year: type: integer description: The four-digit card expiry year, in `YYYY` format. cvv2: type: integer description: The card validation code. Supported only when making a payment but not when saving a credit card for future use. first_name: type: string description: The first name of the card holder. last_name: type: string description: The last name of the card holder. external_customer_id: maxLength: 256 type: string description: 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. state: type: string description: The state of the funding instrument. readOnly: true enum: - expired - ok valid_until: type: string description: The date and time when the credit card becomes unusable from the vault, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). 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. readOnly: true links: type: array description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: type: object allOf: - $ref: "#/components/schemas/link_description" - type: object x-publicDocsSchemaName: link_description - type: object readOnly: true billing_address: type: object allOf: - $ref: "#/components/schemas/address" - type: object description: The billing address associated with this card. - type: object x-publicDocsSchemaName: address description: The credit card that can be used to fund a payment. x-visibility: extent: EXTERNAL x-links: - rel: self href: credit-card/{id} method: GET address_postal_code_validation: title: address_postal_code_validation type: object x-oneOf: - country_code: AL validation_regex: \d{4} - country_code: AR validation_regex: ([A-HJ-NP-Z])?\d{4}([A-Z]{3})? - country_code: AT validation_regex: \d{4} - country_code: AU validation_regex: \d{4} - country_code: BE validation_regex: "[1-9]\\d{3}" - country_code: BG validation_regex: \d{4} - country_code: BN validation_regex: "[A-Z]{2}[ ]?\\d{4}" - country_code: BR validation_regex: \d{5}[\-]?\d{3} - country_code: BT validation_regex: \d{5} - country_code: BY validation_regex: \d{6} - country_code: CA validation_regex: "[ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJ-NPRSTV-Z][ ]?\\d[ABCEGHJ-NPRSTV-Z]\\d" - country_code: CH validation_regex: \d{4} - country_code: CL validation_regex: \d{7} - country_code: CN validation_regex: \d{6} - country_code: CO validation_regex: \d{6} - country_code: CR validation_regex: \d{4,5}|\d{3}-\d{4} - country_code: CY validation_regex: \d{4} - country_code: CZ validation_regex: \d{3}[ ]?\d{2} - country_code: DE validation_regex: (0[1-9]|[1-9]\d)\d{3} - country_code: DK validation_regex: \d{4} - country_code: DO validation_regex: \d{5} - country_code: EC validation_regex: \d{6} - country_code: EE validation_regex: \d{5} - country_code: ES validation_regex: \d{5} - country_code: FI validation_regex: \d{5} - country_code: FM validation_regex: (9694[1-4])(?:[ \-]?(\d{4}))? - country_code: FO validation_regex: (FO[ \-]?)?\d{3} - country_code: FR validation_regex: \d{2}[ ]?\d{3} - country_code: GB validation_regex: GIR[ ]?0AA|(?:(?:AB|AL|B|BA|BB|BD|BF|BH|BL|BN|BR|BS|BT|BX|CA|CB|CF|CH|CM|CO|CR|CT|CV|CW|DA|DD|DE|DG|DH|DL|DN|DT|DY|E|EC|EH|EN|EX|FK|FY|G|GL|GY|GU|HA|HD|HG|HP|HR|HS|HU|HX|IG|IM|IP|IV|JE|KA|KT|KW|KY|L|LA|LD|LE|LL|LN|LS|LU|M|ME|MK|ML|N|NE|NG|NN|NP|NR|NW|OL|OX|PA|PE|PH|PL|PO|PR|RG|RH|RM|S|SA|SE|SG|SK|SL|SM|SN|SO|SP|SR|SS|ST|SW|SY|TA|TD|TF|TN|TQ|TR|TS|TW|UB|W|WA|WC|WD|WF|WN|WR|WS|WV|YO|ZE)(?:\d[\dA-Z]?[ ]?\d[ABD-HJLN-UW-Z]{2}))|BFPO[ ]?\d{1,4} - country_code: GF validation_regex: 9[78]3\d{2} - country_code: GL validation_regex: (DK-?)?39\d{2} - country_code: GP validation_regex: 9[78][01]\d{2} - country_code: GR validation_regex: \d{3}[ ]?\d{2} - country_code: HR validation_regex: \d{5} - country_code: HU validation_regex: \d{4} - country_code: ID validation_regex: \d{5} - country_code: IE validation_regex: "[A-Za-z0-9 \\-]{1,10}" - country_code: IL validation_regex: \d{5}(\d{2})? - country_code: IN validation_regex: \d{3}[ ]?\d{3} - country_code: IS validation_regex: \d{3} - country_code: IT validation_regex: \d{5} - country_code: JP validation_regex: \d{3}-?\d{4} - country_code: KG validation_regex: \d{6} - country_code: KH validation_regex: \d{5} - country_code: KR validation_regex: \d{5} - country_code: KW validation_regex: \d{5} - country_code: KZ validation_regex: \d{6} - country_code: LA validation_regex: \d{5} - country_code: LK validation_regex: \d{5} - country_code: LT validation_regex: \d{5} - country_code: LU validation_regex: \d{4} - country_code: LV validation_regex: LV-\d{4} - country_code: MA validation_regex: \d{5} - country_code: MC validation_regex: 980\d{2} - country_code: MD validation_regex: \d{4} - country_code: ME validation_regex: 8\d{4} - country_code: MK validation_regex: \d{4} - country_code: MN validation_regex: \d{5} - country_code: MQ validation_regex: 9[78]2\d{2} - country_code: MT validation_regex: "[A-Z]{3}[ ]?\\d{2,4}" - country_code: MU validation_regex: \d{3}(?:\d{2}|[A-Z]{2}\d{3}) - country_code: MV validation_regex: \d{5} - country_code: MX validation_regex: \d{5} - country_code: MY validation_regex: \d{5} - country_code: NG validation_regex: \d{6} - country_code: NL validation_regex: \d{4}[ ]?[A-Z]{2} - country_code: NO validation_regex: \d{4} - country_code: NP validation_regex: \d{5} - country_code: NZ validation_regex: \d{4} - country_code: OM validation_regex: (?:PC )?\d{3} - country_code: PE validation_regex: (?:LIMA[ ]?\d{1,2}|CALLAO[ ]?0?\d)|[0-2]?\d{1,4} - country_code: PH validation_regex: \d{4} - country_code: PL validation_regex: \d{2}-\d{3} - country_code: PT validation_regex: \d{4}([\-]?\d{3})? - country_code: PY validation_regex: \d{4} - country_code: RE validation_regex: 9[78]4\d{2} - country_code: RO validation_regex: \d{6} - country_code: RS validation_regex: \d{5,6} - country_code: RU validation_regex: "[1-9]\\d{5}" - country_code: SA validation_regex: \d{5}([\-]?\d{4})? - country_code: SE validation_regex: \d{3}[ ]?\d{2} - country_code: SG validation_regex: \d{6} - country_code: SI validation_regex: \d{4} - country_code: SK validation_regex: \d{3}[ ]?\d{2} - country_code: SM validation_regex: 4789\d - country_code: SV validation_regex: (?:CP[ ]?)?[1-3][1-7][0-2]\d - country_code: TH validation_regex: \d{5} - country_code: TR validation_regex: \d{5} - country_code: TW validation_regex: \d{3}(\d{2})? - country_code: UA validation_regex: \d{5} - country_code: US validation_regex: \d{5}([ \-]?\d{4})? - country_code: UY validation_regex: "[1-9]\\d{4}" - country_code: VA validation_regex: "00120" - country_code: VE validation_regex: "[1-8]\\d{3}([\\-]?[A-Z])?" - country_code: VN validation_regex: \d{6} - country_code: YT validation_regex: 976\d{2} - country_code: ZA validation_regex: \d{4} - country_code: C2 validation_regex: \d{6} country_code: title: country_code maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ type: string description: The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
format: ppaas_common_country_code_v2 shipping_address: title: Shipping Address description: The shipping address for a payment. Must be provided if it differs from the default address. allOf: - type: object properties: recipient_name: type: string description: The name of the recipient at this address. x-visibility: extent: EXTERNAL default_address: type: boolean description: The default shipping address of the payer. readOnly: true x-visibility: extent: EXTERNAL - allOf: - $ref: "#/components/schemas/address" - type: object x-publicDocsSchemaName: address x-visibility: extent: EXTERNAL payment_definition: title: Payment Definition required: - amount - cycles - frequency - frequency_interval - name - type type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true name: maxLength: 128 type: string description: The payment definition name. type: type: string description: The payment definition type. enum: - TRIAL - REGULAR frequency_interval: type: string description: The interval at which the customer is charged. Value cannot be greater than 12 months. frequency: type: string description: 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.
x-enum: - value: WEEK description: The payment is weekly. - value: DAY description: The payment is daily. - value: YEAR description: The payment is yearly. - value: MONTH description: The payment is monthly. cycles: type: string description: The number of payment cycles in this definition. For infinite plans with a regular payment definition, set `cycles` to `0`. charge_models: type: array description: An array of shipping fee and tax information for this definition. items: type: object allOf: - type: object x-publicDocsSchemaName: charge_model - $ref: "#/components/schemas/charge_models" amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount to charge at the end of each payment cycle for this definition. - type: object x-publicDocsSchemaName: currency description: The payment definition, which defines a regular or trial payment. x-visibility: extent: EXTERNAL terms: title: Terms required: - amount_range - buyer_editable - max_billing_amount - occurrences - type type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true type: type: string description: The term type. x-enum: - value: MONTHLY description: The term is monthly. - value: WEEKLY description: The term is weekly. - value: YEARLY description: The term is yearly. occurrences: type: string description: The number of times that money can be pulled during this term. buyer_editable: type: string description: Indicates whether the customer can edit the amount in this term. max_billing_amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount of the maximum billing amount associated with this term. - type: object x-publicDocsSchemaName: currency amount_range: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The amount range for this term. - type: object x-publicDocsSchemaName: currency description: The plan terms. x-visibility: extent: EXTERNAL charge_models: title: Charge Models required: - amount - type type: object properties: id: maxLength: 128 type: string description: The PayPal-generated ID for the resource. readOnly: true type: maxLength: 20 type: string description: The charge model type. enum: - TAX - SHIPPING amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount for this charge model. - type: object x-publicDocsSchemaName: currency description: The charge model for a payment definition. A charge model defines shipping fee and tax information. x-visibility: extent: EXTERNAL x-publicDocsSchemaName: charge_model error_details: title: Error Details required: - field - issue type: object properties: field: type: string description: The name of the field that caused the error. issue: type: string description: The reason for the error. description: The error details. Required for client-side `4XX` errors. patch: title: Patch required: - op type: object properties: op: type: string description: The operation. x-enum: - value: add description: Depending on the target location reference, completes one of these functions:The value parameter defines the value to add. For more information, see 4.1. add. - value: remove description: Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove. - value: replace description: 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. - value: move description: 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. - value: copy description: 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. - value: test description: 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. path: type: string description: The JSON Pointer to the target document location at which to complete the operation. value: title: Patch Value type: object properties: {} description: The value to apply. The remove operation does not require a value. from: type: string description: The JSON Pointer to the target document location from which to move the value. Required for the move operation. description: The JSON patch object to apply partial updates to resources. agreement_transaction: title: Agreement Transaction required: - amount - fee_amount - net_amount type: object properties: transaction_id: type: string description: The ID of the transaction. readOnly: true status: type: string description: The current status of the transaction. Value is: readOnly: true enum: - Completed - Partially_Refunded - Pending - Refunded - Denied transaction_type: type: string description: The type of transaction. Typically, `Recurring Payment`. readOnly: true payer_email: type: string description: The email ID of the customer. readOnly: true payer_name: type: string description: The business name of the customer. readOnly: true time_stamp: type: string description: The date and time when the transaction occurred, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true time_zone: type: string description: The time zone of the `update_time` field. readOnly: true amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount of the transaction. - type: object x-publicDocsSchemaName: currency fee_amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount of the transaction fee. - type: object x-publicDocsSchemaName: currency net_amount: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount of the transaction net amount. - type: object x-publicDocsSchemaName: currency description: The agreement transaction. x-visibility: extent: EXTERNAL securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /api/oauth-proxy scopes: https://uri.paypal.com/services/subscriptions: Create and Manage a billing-agreement x-deprecated: see: v1/billing/plans since_version: "1.1" x-errors: - name: ACCOUNT_RESTRICTED message: This transaction cannot be processed. Contact PayPal Customer Service. description: This account is restricted. - name: ADDRESS_INVALID message: The user address is not valid. description: The address is not valid. - name: BA_TOKEN message: Invalid request - see details. description: Invalid agreement ID. The ID is the B-XXXXXXXXXXXXXXXXXX type. - name: BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE message: The billed amount should be less than the outstanding balance. description: The billed amount is too large. - name: BUSADD_STATE_UNSUPPORTED message: This transaction cannot be processed. description: The country listed for your business address is not currently supported. - name: CALL_FAILED_PAYMENT message: Payment is failing. description: The payment is failing. - name: CANNOT_FIND_PROFILE_DESC message: The profile description is not valid. description: Provide a valid agreement description. - name: CANNOT_MIX_CURRENCIES message: The currency code is not valid. All currency codes much match. description: Use same currency code for all amount objects. - name: CANT_INCREASE_OUTSTANDING_AMOUNT message: Cannot increase the delinquent amount. description: You cannot increase the outstanding amount for the bill. - name: CC_STATUS_INVALID message: Profile is not active. description: The state of the profile is not active. - name: CC_TYPE_NOT_SUPPORTED message: The credit card type is not supported. description: Use another type of credit card. - name: DPRP_DISABLED message: DPRP is disabled for this merchant. description: 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. - name: DUPLICATE_REQUEST_ID message: The value of PayPal-Request-Id header has already been used. description: Use a unique PayPal-Request-Id header value to resend the request. - name: EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED message: Business error. description: The buyer has not approved this token. - name: EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN message: Business error. description: A session validation error occurred. The session does not belong to the merchant. - name: FEATURE_DISABLED message: This transaction cannot be processed. description: This feature is disabled. - name: FEATURE_NOT_AVAILABLE message: Because the recurring payments feature is not currently available, you must try again later. description: This feature is not available. - name: GATEWAY_DECLINE_CVV2 message: This transaction cannot be processed. Enter a valid credit card verification number. description: The verification number is not valid. - name: INTERNAL_ERROR message: Internal Error. description: Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support. - name: INTERNAL_SERVICE_ERROR message: An internal service error has occurred. description: Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support. - name: INVALID_AMOUNT message: The bill amount must be greater than 0. description: Specify a valid amount. - name: INVALID_ARGS message: Invalid argument. The description field or custom field is empty and the status is active. description: Pass correct arguments in the description field and make sure that the status is active. - name: INVALID_CC_NUMBER message: This transaction cannot be processed. Enter a valid credit card number and type. description: The credit card number and type are not valid. - name: INVALID_CURRENCY message: This transaction cannot be processed due to an unsupported currency. description: This currency is not supported. - name: INVALID_ID_PASSED message: Business error. description: The ID is invalid ID. - name: INVALID_PROFILE_ACTION message: The action value is not valid. description: Enter a valid action. - name: INVALID_PROFILE_ID message: The profile ID is not valid. description: Enter a valid profile ID. - name: INVALID_PROFILE_STATUS message: The profile status must be one of (A)ctive, (C)ancelled, or e(X)pired. description: Enter a valid profile status. - name: INVALID_SECURITY_CTX message: Business error. description: The security context is invalid. - name: INVALID_STATUS_TO_CANCEL message: The status is not valid for the suspend action. The profile must be active. description: The agreement must be active before you can suspend it. - name: INVALID_STATUS_TO_REACTIVATE message: The activation type is not valid. description: Pass a valid activation type. - name: INVALID_STATUS_TO_SUSPEND message: Invalid profile status for reactivate action. Profile must be suspended. description: To complete this action, you must first suspend the agreement. - name: INVALID_TOKEN message: The token is missing or is invalid. description: Enter a valid token. - name: MALFORMED_REQUEST message: The request JSON is not well formed. description: Review the JSON request. - name: MERCHANT_ACCOUNT_DENIED message: Merchant account is denied. description: The merchant account is denied. - name: MERCHANT_COUNTRY_NOT_SUPPORTED message: The merchant country is not supported. description: This country is not supported. - name: MERCHANT_ID_NOT_AUTHORIZED message: Business error. description: The merchant ID not authorized to get the details. - name: MISSING_CVV2 message: This transaction cannot be processed without a credit card verification number. description: Enter the credit card verification number. - name: OUTSTANDING_PAYMENT_ALREADY_SCHEDULED message: Another outstanding payment is scheduled. description: Another payment is already scheduled. - name: PAYER_ACCOUNT_DENIED message: The payer's account is denied. description: The payer's account is denied. - name: PAYER_COUNTRY_NOT_SUPPORTED message: The payer's country is currently not supported. description: This country is not supported. - name: PAYMENT_METHOD message: Invalid request - see details. description: Invalid payment method. Valid value is PAYPAL. - name: PLAN_TYPE message: Invalid request - see details. description: Invalid type mentioned. Valid values are MERCHANT_INITIATED_BILLING or CHANNEL_INITIATED_BILLING. - name: PROCESSOR_DECLINE_INVALID_CC_COUNTRY message: This credit card was issued from an unsupported country. description: This country is not supported. - name: RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS message: The recurring payment was scheduled within 24 hours, so the bill outstanding amount cannot be processed. description: This bill outstanding amount cannot be processed. - name: REQUIRED_SCOPE_MISSING message: Access token does not have required scope. description: Obtain user consent by using the correct scope for this request type. - name: REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED message: Authorization error. description: This facilitator account is not permitted for Channel Initiated Billing. - name: REFUSED_MARK_REF_TXN_NOT_ENABLED message: Authorization error. description: This merchant account is not permitted to create Merchant Initiated Billing Agreement. - name: RT_AGREEMENT_ALREADY_CANCELED message: Business error. description: "Failed Request: Agreement is already cancelled / Invalid agreement state." - name: RT_INVALID_AGREEMENT_ID message: Business error. description: No matching record found. - name: SET_BALANCE_INVALID_CURRENCY_CODE message: Invalid currency for delinquent amount. description: Specify a valid currency in the bill-balance call. - name: SHIPPING_ADDRESS_NOT_IN_RESIDENCE_COUNTRY message: This transaction cannot be processed. The shipping country is not allowed by the buyer's country of residence. description: The shipping country is not supported. - name: SHP_INVALID_COUNTRY_CODE message: This transaction cannot be processed. Enter a valid country code in the shipping address. description: Enter a valid country code. - name: START_DATE_INVALID_FORMAT message: The subscription start date must be valid. description: Specify a valid start date in Internet date and time format. The start date must be greater than the current date. - name: STATUS_INVALID message: The profile status is not valid for the reactivate action. The status must be active. description: Make sure that the status is active. - name: SUBSCRIPTION_UNMAPPED_ERROR message: An internal error occurred. description: An internal error occurred. - name: TIME_TO_UPDATE_CLOSE_TO_BILLING_DATE message: The time of the update is too close to the billing date. description: You cannot make an update this close to the billing date. - name: TOKEN_NOT_FOUND message: Internal error. description: Invalid BA-Token Identifier. Valid token has the BA-XXXXXXXXXXXXXXXXX format. - name: UNAUTHORIZED_AGREEMENT_REQUEST message: You do not have permission to create this agreement. description: You are not authorized to create this agreement. - name: USR_BILLING_AGRMNT_NOT_ACTIVE message: This transaction cannot be processed due to an invalid merchant configuration. description: The merchant configuration is not valid. - name: VALIDATION_ERROR message: Invalid request - see details. description: Your request has a validation error. - name: WALLET_TOO_MANY_ATTEMPTS message: You have exceeded the maximum number of payment attempts for this token. description: Create a token and use it to create an agreement. x-requestValidationIssues: - name: ADD_OPERATION_NOT_SUPPORTED message: Add operation not supported now. - name: AMT_BLANK message: Amount cannot be blank. - name: ASD_INVALID_AMOUNT message: Amount should be non-negative number with a maximum of two decimal places separated by `.`, optional thousands separator `,`, limited to seven digits before the decimal point. - name: ASD_INVALID_NOTE message: Note is missing from the request or note length is too long. - name: AUTO_BILL_AMT message: Invalid `autobill_amount` type. Can be `yes` or `no`. - name: CAN_UPDATE_TEMPLATE_ONLY_IN_CREATED_STATE message: Update of a template only allowed in `CREATED` state. - name: CANT_ACTIVATE_ACTIVE_TEMPLATE message: You can't activate an active template. - name: CANT_DEACTIVATE_INACTIVE_TEMPLATE message: You can't deactivate an inactive template. - name: CANT_MODIFY_DELETED_TEMPLATE message: Invalid template ID. - name: CHARGE_MODEL_ID_INVALID message: Invalid charge model ID. - name: CM_INVALID_AMOUNT message: Charge model amount should be non-negative number with a maximum of two decimal places separated by `.`, optional thousands separator `,`, limited to seven digits before the decimal point. - name: CM_INVALID_ID message: Charge model ID should not be null or blank. - name: CM_INVALID_TYPE message: Charge model type is invalid or null. Valid parameters are `SHIPPING` or `TAX`. - name: EC_TOKEN_INVALID message: Invalid payment token. - name: FAIL_INIT_AMT_ACTION message: Invalid `fail_initamt_action`. Can be `continue` or `cancel`. - name: FractionDigitsNotAllowed message: Fraction digits are not allowed with this currency. - name: FREQ_MORE_THAN_YEAR message: Frequency more than year is not supported. - name: INVALID_AGREEMENT_CURRENCIES message: All amounts with in a agreement should have same currency. - name: INVALID_END_DATE message: "`end_date` should be after `start_date`." - name: INVALID_FIXED_PD_VALUE message: "`no_of_cycles` can't be null or 0 for a `FIXED` plan." - name: INVALID_INFINITE_PD_VALUE message: If payment definition type is `REGULAR`, `no_of_cycles` can only be null or 0 for an `UNLIMITED` plan. - name: INVALID_OCM_LIST message: Override charge models provided should have different `charge_ids`. - name: INVALID_OPERATION message: Invalid operation name. Can be `add`, `remove`, or `replace`. - name: INVALID_PATCH_PATH message: Invalid path provided. - name: INVALID_PD_SPECIFIED message: You can't create template with only `TRIAL` as payment definition. - name: INVALID_PLAN_CURRENCIES message: All amounts within a plan should have same currency. - name: INVALID_REGULAR_AMOUNT message: Amount passed in regular payment definition should be more than zero. - name: INVALID_STATE message: Invalid state entered. Value is `created`, `deleted`, `inactive`, or `active`. - name: INVALID_STATE_CHANGE_REQUEST message: Requested state change is invalid. - name: INVALID_TRIAL_CYCLE_VALUE message: For `TRIAL` payment definition, number of cycles can't be null or 0. - name: INVALID_URL message: Missing or invalid URL entered. Max length is 2048. - name: InvalidAlphanumeric message: Must be alphanumeric. - name: InvalidAlphaNumPlus message: "Must contain only these characters: `a`-`z`, `A`-`Z`, `0`-`9`, punctuation (`.`,`,`,`#`,`-`, or `'`), and embedded spaces." - name: InvalidCurrencyCode message: Currency code must be a three-character ISO 4217 upper case value. - name: InvalidDateTime message: The `date_time`, although formatted properly, does not represent a valid date and time. - name: InvalidDateTimeFormat message: Must be a `date_time` string of form `yyyy-mm-ddThh:mm:ss(.sss)?Z`. - name: InvalidFormatCurrencyAmount message: Currency amount must be non-negative number, may optionally contain exactly two decimal places separated by `.`, optional thousands separator `,`, limited to seven digits before the decimal point. - name: InvalidFormatUrl message: Invalid URL. - name: InvalidIntegerFormat message: Invalid value. - name: InvalidNumeric message: Must be numeric. - name: InvalidPositiveNumber message: Must be a positive integer. - name: InvalidQueryParams message: Invalid to specify both `start_id` and `start_index` query params. - name: MALFORMED_REQUEST message: The request JSON is not well formed. - name: MAX_FAIL_ATTEMPTS message: "`max_fail_attempts` is invalid or null. It should be positive integer with max value 999." - name: MP_INVALID_AUTOBILL message: Invalid `autobill_amount` type. Can be `yes` or `no`. - name: MP_INVALID_INIT_FAIL_AMT_ACTION message: Invalid initial amount action. Value is `CANCEL`, `CONTINUE`. - name: MustNotBeBlank message: Must not be blank. - name: PAYER_EXTRA_CC_DETAILS message: No funding instruments need to be passed for payment method as PayPal. - name: PAYER_INVALID_PYMT_METHOD message: Invalid payment method provided. Value is `PAYPAL` or `CREDIT_CARD`. - name: PAYER_NO_CC_DETAILS message: Funding instrument details are missing or funding instrument not supported. Only credit-card is supported. - name: PAYMENT_DEF_ID_INVALID message: Invalid payment definition ID. - name: PD_INVALID_AMT message: Amount should a positive number greater than 0 with a maximum of two decimal places separated by `.` with optional thousands separator `,`, limited to seven digits before the decimal point. - name: PD_INVALID_CMLIST message: Charge models within a payment definition should have distinct `Types`. - name: PD_INVALID_CURRENCY_OBJECT message: Currency object of payment definition can't be null. - name: PD_INVALID_CYCLES message: Number of cycles should be positive numeric and less than 10000. - name: PD_INVALID_FREQ message: Payment definition frequency type passed is either null or invalid. Value is `DAY`, `WEEK`, `MONTH`, or `YEAR`. - name: PD_INVALID_FREQ_COUNT message: Payment definition frequency count should be positive numeric. - name: PD_INVALID_NAME message: Field is mandatory. Limit of 127 characters. - name: PD_INVALID_TYPE message: Payment definition type passed is either null or invalid. Value is `TRIAL` or `REGULAR`. - name: QUERYPARAM_INVALID_PAGE_SIZE message: Invalid page size. Value is a positive number that is less than 21. - name: QUERYPARAM_INVALID_SORT_ORDER message: Sort order is invalid. Value is `asc` or `desc`. - name: QUERYPARAM_INVALID_STATUS message: Invalid status, Value is `CREATED`, `ACTIVE`, or `INACTIVE`. - name: QUERYPARAM_INVALID_TOTAL_REQUIRED message: Invalid total required. Value is `yes` or `no`. - name: ReadonlyField message: Not valid to specify this field in a request. - name: REMOVE_OPERATION_NOT_SUPPORTED message: Remove operation not supported. - name: RequiredFieldMissing message: Required field missing. - name: SET_UP_FEE message: The `setup_fee` is invalid or null. It should be a positive number with max value of `9999999`. - name: TEMPLATE_ALREADY_IN_GIVEN_STATE message: Plan already in same state. - name: TEMPLATE_ID_INVALID message: Override charge models provided should have different `charge_ids`. - name: TEMPLATE_ID_INVALID message: Incorrect template ID. - name: TEMPLATE_NOT_ACTIVE message: Plan not in active state. - name: TMP_DESC_FIELD_MISSING message: Field is mandatory. Limit of 127 characters. - name: TMP_INVALID_MPREF message: Merchant preferences are mandatory. - name: TMP_INVALID_PDS message: Payment definitions are invalid. Valid parameters are `REGULAR` or combination of `TRIAL` and `REGULAR`. - name: TMP_INVALID_TYPE message: Template type is either null or invalid. Valid parameters are `UNLIMITED` or `FIXED`. - name: TMP_NAME_FIELD_MISSING message: Field is mandatory. Limit of 127 characters. - name: UNWANTED_FIELD_MESSAGE message: Patch is not supported for this field. - name: VALID_DATE_FORMAT message: "`start_date` and `end_date` cannot be null."