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