Billing Agreements(1)

?This API is currently not supported by our SDK

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.

operation/billing-agreements.post Create agreement

post/v1/payments/billing-agreements

Try it

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.

SecurityOauth2

Request

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


name required	string<= 128 characters The agreement name.
description required	string<= 128 characters The agreement description.
start_date required	string<date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a `2017-01-02T14:36:21Z` start date and time for an account in the Berlin time zone (UTC + 1) to `2017-01-02T00:00:00`. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal `2017-01-02T00:00:00` start date and time becomes `2017-01-01T23:00:00` externally.
agreement_details	object (Agreement Details) The agreement details.
payer required	object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
override_merchant_preferences	object (Merchant Preferences) 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.
override_charge_models	Array of objects (Override Charge Model) 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.
plan required	object (Plan) The ID of the plan on which this agreement is based.
shipping_address	object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address.

Responses

201 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.

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 201 - Create Credit Card AgreementSample 1 - 201 - Create Credit Card Agreement

Copy

Expand allCollapse all

`{"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"

}

}

}

]

}

Response samples

application/json

Sample 1 - 201 - Create Credit Card AgreementSample 1 - 201 - Create Credit Card Agreement

Copy

Expand allCollapse all

`{"id": "I-Y6TL8T5KT95R",

"state": "Active",

"description": "Credit card payment.",

"payer": {"payment_method": "credit_card",

"payer_info": {"email": "johndoe@example.com"

"funding_instruments": [{"credit_card": {"type": "visa",

"number": "3864",

"expire_month": 12,

"expire_year": 2021,

"start_month": "11",

"start_year": "2016",

"billing_address": {"line1": "065769 Holcomb Bridge Road #141",

"line2": "5713 E Dimond Boulevard #B9",

"city": "Wichita",

"state": "KS",

"postal_code": "67202",

"country_code": "US"

}

}

}

]

"plan": {"id": "P-2PL786081D358645F6NWEKFQ",

"name": "Plan with Regular and Trial Payment Definitions",

"description": "Plan with regular and trial payment definitions.",

"type": "FIXED",

"payment_definitions": [{"name": "Trial payment definition",

"type": "TRIAL",

"frequency": "MONTH",

"amount": {"value": "0",

"currency": "USD"

},

"cycles": "2",

"charge_models": [{"type": "TAX",

"amount": {"value": "0",

"currency": "USD"

}

},

{"type": "SHIPPING",

"amount": {"value": "0",

"currency": "USD"

}

}

],

"frequency_interval": "1"

},

{"name": "Regular payment definition",

"type": "REGULAR",

"frequency": "MONTH",

"amount": {"value": "5.99",

"currency": "USD"

},

"cycles": "10",

"charge_models": [{"type": "TAX",

"amount": {"value": "0.29",

"currency": "USD"

}

},

{"type": "SHIPPING",

"amount": {"value": "0.20",

"currency": "USD"

}

}

],

"frequency_interval": "1"

}

],

"merchant_preferences": {"setup_fee": {"value": "0.40",

"currency": "USD"

"return_url": "https://example.com/",

"cancel_url": "https://example.com/cancel",

"max_fail_attempts": "3",

"auto_bill_amount": "YES"

"links": [ ],

"currency_code": "USD"

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-Y6TL8T5KT95R",

"rel": "self",

"method": "GET"

}

],

"start_date": "2016-12-23T08:00:00Z",

"agreement_details": {"outstanding_balance": {"value": "0.00",

"currency": "USD"

"cycles_remaining": "12",

"cycles_completed": "0",

"next_billing_date": "2017-01-23T08:00:00Z",

"last_payment_date": "2016-12-23T08:00:00Z",

"last_payment_amount": {"value": "0.40",

"currency": "USD"

"final_payment_date": "2017-09-23T08:00:00Z",

"failed_payment_count": "0"

}

operation/billing-agreements.agreement-execute Execute agreement

post/v1/payments/billing-agreements/{payment_token}/agreement-execute

Try it

Executes a billing agreement, by ID, after customer approval.

SecurityOauth2

Request

path Parameters


payment_token required	string The ID of the agreement to execute.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

any

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 200 - Create PayPal AgreementSample 1 - 200 - Create PayPal Agreement

Copy

{ }

Response samples

application/json

Sample 1 - 200 - Create PayPal AgreementSample 1 - 200 - Create PayPal Agreement

Copy

Expand allCollapse all

`{"id": "I-1TJ3GAGG82Y9",

"state": "Active",

"description": "Monthly agreement with free trial payment definition.",

"payer": {"payment_method": "paypal",

"status": "unverified",

"payer_info": {"email": "johndoe@example.com",

"first_name": "John",

"last_name": "Doe",

"payer_id": "NEW8A85AK4ET4",

"shipping_address": {"recipient_name": "John Doe",

"line1": "751235 Stout Drive",

"line2": "0976249 Elizabeth Court",

"city": "Quimby",

"state": "IA",

"postal_code": "51049",

"country_code": "US"

}

"plan": {"name": "Plan with Regular and Trial Payment Definitions",

"description": "Plan with regular and trial payment definitions.",

"type": "FIXED",

"payment_definitions": [{"name": "Trial payment definition",

"type": "TRIAL",

"frequency": "MONTH",

"amount": {"value": "0.00",

"currency": "USD"

},

"cycles": "2",

"charge_models": [{"type": "TAX",

"amount": {"value": "0.00",

"currency": "USD"

}

},

{"type": "SHIPPING",

"amount": {"value": "0.00",

"currency": "USD"

}

}

],

"frequency_interval": "1"

},

{"name": "Regular payment definition",

"type": "REGULAR",

"frequency": "MONTH",

"amount": {"value": "5.99",

"currency": "USD"

},

"cycles": "10",

"charge_models": [{"type": "TAX",

"amount": {"value": "0.29",

"currency": "USD"

}

},

{"type": "SHIPPING",

"amount": {"value": "0.20",

"currency": "USD"

}

}

],

"frequency_interval": "1"

}

],

"merchant_preferences": {"setup_fee": {"value": "0.40",

"currency": "USD"

"return_url": "https://example.com",

"cancel_url": "https://example.com/cancel",

"max_fail_attempts": "2",

"auto_bill_amount": "YES"

"links": [ ],

"currency_code": "USD"

"start_date": "2016-12-23T08:00:00Z",

"shipping_address": {"recipient_name": "John Doe",

"line1": "751235 Stout Drive",

"line2": "0976249 Elizabeth Court",

"city": "Quimby",

"state": "IA",

"postal_code": "51049",

"country_code": "US"

"agreement_details": {"outstanding_balance": {"value": "0.00",

"currency": "USD"

"cycles_remaining": "2",

"cycles_completed": "0",

"next_billing_date": "2017-01-23T08:00:00Z",

"last_payment_date": "2016-12-23T08:00:00Z",

"last_payment_amount": {"value": "0.40",

"currency": "USD"

"final_payment_date": "2017-09-23T08:00:00Z",

"failed_payment_count": "0"

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9",

"rel": "self",

"method": "GET"

}

]

operation/billing-agreements.get Show agreement details

get/v1/payments/billing-agreements/{agreement_id}

Try it

Shows details for a billing agreement, by ID.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement for which to show details.

Responses

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

Request samples

cURL

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-5D3XDN2D5FH1 \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'

Response samples

application/json

Sample 1 - 200 - Show Agreement DetailsSample 1 - 200 - Show Agreement Details

Copy

Expand allCollapse all

`{"id": "I-1TJ3GAGG82Y9",

"state": "Active",

"description": "Monthly agreement with free trial payment definition.",

"payer": {"payment_method": "paypal",

"status": "unverified",

"payer_info": {"email": "johndoe@example.com",

"first_name": "John",

"last_name": "Doe",

"payer_id": "NEW8A85AK4ET4",

"shipping_address": {"recipient_name": "John Doe",

"line1": "751235 Stout Drive",

"line2": "0976249 Elizabeth Court",

"city": "Quimby",

"state": "IA",

"postal_code": "51049",

"country_code": "US"

}

"plan": {"name": "Plan with Regular and Trial Payment Definitions",

"description": "Plan with regular and trial payment definitions.",

"type": "FIXED",

"merchant_preferences": {"setup_fee": {"value": "0.40",

"currency": "USD"

"return_url": "https://example.com",

"cancel_url": "https://example.com/cancel",

"max_fail_attempts": "2",

"auto_bill_amount": "YES"

"links": [ ],

"currency_code": "USD"

"start_date": "2016-12-23T08:00:00Z",

"shipping_address": {"recipient_name": "John Doe",

"line1": "751235 Stout Drive",

"line2": "0976249 Elizabeth Court",

"city": "Quimby",

"state": "IA",

"postal_code": "51049",

"country_code": "US"

"agreement_details": {"outstanding_balance": {"currency": "USD",

"value": "0.00"

"cycles_remaining": "2",

"cycles_completed": "0",

"next_billing_date": "2017-01-23T08:00:00Z",

"last_payment_date": "2016-12-23T08:00:00Z",

"last_payment_amount": {"currency": "USD",

"value": "0.40"

"final_payment_date": "2017-09-23T08:00:00Z",

"failed_payment_count": "0"

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend",

"rel": "suspend",

"method": "POST"

},

{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate",

"rel": "re_activate",

"method": "POST"

},

{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel",

"rel": "cancel",

"method": "POST"

},

{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance",

"rel": "self",

"method": "POST"

},

{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance",

"rel": "self",

"method": "POST"

}

]

operation/billing-agreements.patch Update agreement

patch/v1/payments/billing-agreements/{agreement_id}

Try it

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.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement to update.

Request Body schema: application/json

Array

| op
required | string

The operation.

Enum Value	Description
add	Depending on the target location reference, completes one of these functions: - The target location is an array index. Inserts a new value into the array at the specified index. - The target location is an object parameter that does not already exist. Adds a new parameter to the object. - The target location is an object parameter that does exist. Replaces that parameter's value. The `value` parameter defines the value to add. For more information, see 4.1. add.
remove	Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace	Replaces the value at the target location with a new value. The operation object must contain a `value` parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move	Removes the value at a specified location and adds it to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the `from` location must exist. For more information, see 4.4. move.
copy	Copies the value at a specified location to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the `from` location must exist. For more information, see 4.5. copy.
test	Tests that a value at the target location is equal to a specified value. The operation object must contain a `value` parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the `value` value. For test, `equal` indicates that the value at the target location and the value that `value` defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain 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.
objects	Contain 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 | string
The JSON Pointer to the target document location at which to complete the operation. | | value | object (Patch Value)
The value to apply. The remove operation does not require a value. | | from | string
The JSON Pointer to the target document location from which to move the value. Required for the move operation. |

Responses

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

Request samples

Payload
cURL

application/json

Sample 1 - 200 - Update AgreementSample 1 - 200 - Update Agreement

Copy

Expand allCollapse all

[{"op": "replace",\ \ "path": "/",\ \ "value": {"description": "Updated description.",\ \ "start_date": "2017-12-22T09:13:49Z",\ \ "shipping_address": {"line1": "Hotel Blue Diamond",\ \ "line2": "Church Street",\ \ "city": "San Jose",\ \ "state": "CA",\ \ "postal_code": "95112",\ \ "country_code": "US"\ \ }\ \ }\ \ }\ \ ]

Response samples

application/json

Sample 1 - 200 - Update AgreementSample 1 - 200 - Update Agreement

Copy

{ }

operation/billing-agreements.suspend Suspend agreement

post/v1/payments/billing-agreements/{agreement_id}/suspend

Try it

Suspends a billing agreement, by ID.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement to suspend.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


note	string<= 128 characters The reason for the agreement state change.

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 204 - Suspend AgreementSample 1 - 204 - Suspend Agreement

Copy

`{"note": "Suspending the profile."

Response samples

application/json

Sample 1 - 204 - Suspend AgreementSample 1 - 204 - Suspend Agreement

Copy

{ }

operation/billing-agreements.re-activate Reactivate agreement

post/v1/payments/billing-agreements/{agreement_id}/re-activate

Try it

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.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement to reactivate.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


note	string<= 128 characters The reason for the agreement state change.

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 204 - Reactivate AgreementSample 1 - 204 - Reactivate Agreement

Copy

`{"note": "Reactivating the profile."

Response samples

application/json

Sample 1 - 204 - Reactivate AgreementSample 1 - 204 - Reactivate Agreement

Copy

{ }

operation/billing-agreements.cancel Cancel agreement

post/v1/payments/billing-agreements/{agreement_id}/cancel

Try it

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.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement to cancel.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


note	string<= 128 characters The reason for the agreement state change.

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 204 - Cancel AgreementSample 1 - 204 - Cancel Agreement

Copy

`{"note": "Canceling the profile."

Response samples

application/json

Sample 1 - 204 - Cancel AgreementSample 1 - 204 - Cancel Agreement

Copy

{ }

operation/billing-agreements.bill-balance Bill agreement balance

post/v1/payments/billing-agreements/{agreement_id}/bill-balance

Try it

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.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement for which to bill the balance.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


note	string<= 128 characters The reason for the agreement state change.

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 204 - Bill Agreement BalanceSample 1 - 204 - Bill Agreement Balance

Copy

`{"note": "Billing balance amount."

Response samples

application/json

Sample 1 - 204 - Bill Agreement BalanceSample 1 - 204 - Bill Agreement Balance

Copy

{ }

operation/billing-agreements.set-balance Set agreement balance

post/v1/payments/billing-agreements/{agreement_id}/set-balance

Try it

Sets the balance for an agreement, by ID. In the JSON request body, specify the balance currency type and value.

SecurityOauth2

Request

path Parameters


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

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


value required	string<= 32 characters^((-?[0-9]+)\|(-?([0-9]+)?[.][0-9]+))$ 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.
currency required	string<ppaas_common_currency_code_v2> (currency_code) = 3 characters The three-character ISO-4217 currency code that identifies the currency.

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 204 - Set Agreement BalanceSample 1 - 204 - Set Agreement Balance

Copy

`{"value": "100",

"currency": "USD"

Response samples

application/json

Sample 1 - 204 - Set Agreement BalanceSample 1 - 204 - Set Agreement Balance

Copy

{ }

operation/billing-agreements.transactions List agreement transactions

get/v1/payments/billing-agreements/{agreement_id}/transactions

Try it

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.

SecurityOauth2

Request

path Parameters


agreement_id required	string The ID of the agreement for which to list transactions.

query Parameters


start_date	string The start date of the range of transactions to list.
end_date	string The end date of the range of transactions to list.

Responses

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

Request samples

cURL

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/transactions?start_date=2017-06-15&end_date=2017-06-17 \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'

Response samples

application/json

Sample 1 - 200 - List Agreement TransactionsSample 1 - 200 - List Agreement Transactions

Copy

Expand allCollapse all

`{"agreement_transaction_list": [{"transaction_id": "I-V8SSE9WLJGY6",

"status": "Completed",

"transaction_type": "Recurring Payment",

"amount": {"value": "100",

"currency": "USD"

},

"fee_amount": {"value": "1",

"currency": "USD"

},

"net_amount": {"value": "100",

"currency": "USD"

},

"payer_email": "",

"payer_name": " ",

"time_stamp": "2017-06-16T13:46:53Z",

"time_zone": "GMT"

},

{"transaction_id": "I-V8SSE9WLJGY6",

"status": "Denied",

"transaction_type": "Recurring Payment",

"amount": {"value": "100",

"currency": "USD"

},

"fee_amount": {"value": "1",

"currency": "USD"

},

"net_amount": {"value": "100",

"currency": "USD"

},

"payer_email": "",

"payer_name": " ",

"time_stamp": "2017-06-16T13:52:26Z",

"time_zone": "GMT"

},

{"transaction_id": "I-V8SSE9WLJGY6",

"status": "Pending",

"transaction_type": "Recurring Payment",

"amount": {"value": "100",

"currency": "USD"

},

"fee_amount": {"value": "1",

"currency": "USD"

},

"net_amount": {"value": "100",

"currency": "USD"

},

"payer_email": "",

"payer_name": " ",

"time_stamp": "2017-06-16T14:00:23Z",

"time_zone": "GMT"

},

{"transaction_id": "I-V8SSE9WLJGY6",

"status": "Denied",

"transaction_type": "Recurring Payment",

"amount": {"value": "100",

"currency": "USD"

},

"fee_amount": {"value": "1",

"currency": "USD"

},

"net_amount": {"value": "100",

"currency": "USD"

},

"payer_email": "",

"payer_name": " ",

"time_stamp": "2017-06-16T14:02:54Z",

"time_zone": "GMT"

}

]

tag/Errors Errors

section/ACCOUNT_RESTRICTED ACCOUNT_RESTRICTED

Message:

This transaction cannot be processed. Contact PayPal Customer Service.

Description: This account is restricted.

section/ADDRESS_INVALID ADDRESS_INVALID

Message:

The user address is not valid.

Description: The address is not valid.

section/BA_TOKEN BA_TOKEN

Message:

Invalid request - see details.

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

section/BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE

Message:

The billed amount should be less than the outstanding balance.

Description: The billed amount is too large.

section/BUSADD_STATE_UNSUPPORTED BUSADD_STATE_UNSUPPORTED

Message:

This transaction cannot be processed.

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

section/CALL_FAILED_PAYMENT CALL_FAILED_PAYMENT

Message:

Payment is failing.

Description: The payment is failing.

section/CANNOT_FIND_PROFILE_DESC CANNOT_FIND_PROFILE_DESC

Message:

The profile description is not valid.

Description: Provide a valid agreement description.

section/CANNOT_MIX_CURRENCIES CANNOT_MIX_CURRENCIES

Message:

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

Description: Use same currency code for all amount objects.

section/CANT_INCREASE_OUTSTANDING_AMOUNT CANT_INCREASE_OUTSTANDING_AMOUNT

Message:

Cannot increase the delinquent amount.

Description: You cannot increase the outstanding amount for the bill.

section/CC_STATUS_INVALID CC_STATUS_INVALID

Message:

Profile is not active.

Description: The state of the profile is not active.

section/CC_TYPE_NOT_SUPPORTED CC_TYPE_NOT_SUPPORTED

Message:

The credit card type is not supported.

Description: Use another type of credit card.

section/DPRP_DISABLED 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.

section/DUPLICATE_REQUEST_ID 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.

section/EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED

Message:

Business error.

Description: The buyer has not approved this token.

section/EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN

Message:

Business error.

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

section/FEATURE_DISABLED FEATURE_DISABLED

Message:

This transaction cannot be processed.

Description: This feature is disabled.

section/FEATURE_NOT_AVAILABLE FEATURE_NOT_AVAILABLE

Message:

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

Description: This feature is not available.

section/GATEWAY_DECLINE_CVV2 GATEWAY_DECLINE_CVV2

Message:

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

Description: The verification number is not valid.

section/INTERNAL_ERROR INTERNAL_ERROR

Message:

Internal Error.

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

section/INTERNAL_SERVICE_ERROR 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.

section/INVALID_AMOUNT INVALID_AMOUNT

Message:

The bill amount must be greater than 0.

Description: Specify a valid amount.

section/INVALID_ARGS 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.

section/INVALID_CC_NUMBER 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.

section/INVALID_CURRENCY INVALID_CURRENCY

Message:

This transaction cannot be processed due to an unsupported currency.

Description: This currency is not supported.

section/INVALID_ID_PASSED INVALID_ID_PASSED

Message:

Business error.

Description: The ID is invalid ID.

section/INVALID_PROFILE_ACTION INVALID_PROFILE_ACTION

Message:

The action value is not valid.

Description: Enter a valid action.

section/INVALID_PROFILE_ID INVALID_PROFILE_ID

Message:

The profile ID is not valid.

Description: Enter a valid profile ID.

section/INVALID_PROFILE_STATUS 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.

section/INVALID_SECURITY_CTX INVALID_SECURITY_CTX

Message:

Business error.

Description: The security context is invalid.

section/INVALID_STATUS_TO_CANCEL 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.

section/INVALID_STATUS_TO_REACTIVATE INVALID_STATUS_TO_REACTIVATE

Message:

The activation type is not valid.

Description: Pass a valid activation type.

section/INVALID_STATUS_TO_SUSPEND 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.

section/INVALID_TOKEN INVALID_TOKEN

Message:

The token is missing or is invalid.

Description: Enter a valid token.

section/MALFORMED_REQUEST MALFORMED_REQUEST

Message:

The request JSON is not well formed.

Description: Review the JSON request.

section/MERCHANT_ACCOUNT_DENIED MERCHANT_ACCOUNT_DENIED

Message:

Merchant account is denied.

Description: The merchant account is denied.

section/MERCHANT_COUNTRY_NOT_SUPPORTED MERCHANT_COUNTRY_NOT_SUPPORTED

Message:

The merchant country is not supported.

Description: This country is not supported.

section/MERCHANT_ID_NOT_AUTHORIZED MERCHANT_ID_NOT_AUTHORIZED

Message:

Business error.

Description: The merchant ID not authorized to get the details.

section/MISSING_CVV2 MISSING_CVV2

Message:

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

Description: Enter the credit card verification number.

section/OUTSTANDING_PAYMENT_ALREADY_SCHEDULED OUTSTANDING_PAYMENT_ALREADY_SCHEDULED

Message:

Another outstanding payment is scheduled.

Description: Another payment is already scheduled.

section/PAYER_ACCOUNT_DENIED PAYER_ACCOUNT_DENIED

Message:

The payer's account is denied.

Description: The payer's account is denied.

section/PAYER_COUNTRY_NOT_SUPPORTED PAYER_COUNTRY_NOT_SUPPORTED

Message:

The payer's country is currently not supported.

Description: This country is not supported.

section/PAYMENT_METHOD PAYMENT_METHOD

Message:

Invalid request - see details.

Description: Invalid payment method. Valid value is PAYPAL.

section/PLAN_TYPE PLAN_TYPE

Message:

Invalid request - see details.

Description: Invalid type mentioned. Valid values are MERCHANT_INITIATED_BILLING or CHANNEL_INITIATED_BILLING.

section/PROCESSOR_DECLINE_INVALID_CC_COUNTRY PROCESSOR_DECLINE_INVALID_CC_COUNTRY

Message:

This credit card was issued from an unsupported country.

Description: This country is not supported.

section/RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS 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.

section/REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED

Message:

Authorization error.

Description: This facilitator account is not permitted for Channel Initiated Billing.

section/REFUSED_MARK_REF_TXN_NOT_ENABLED REFUSED_MARK_REF_TXN_NOT_ENABLED

Message:

Authorization error.

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

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING

Message:

Access token does not have required scope.

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

section/RT_AGREEMENT_ALREADY_CANCELED RT_AGREEMENT_ALREADY_CANCELED

Message:

Business error.

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

section/RT_INVALID_AGREEMENT_ID RT_INVALID_AGREEMENT_ID

Message:

Business error.

Description: No matching record found.

section/SET_BALANCE_INVALID_CURRENCY_CODE SET_BALANCE_INVALID_CURRENCY_CODE

Message:

Invalid currency for delinquent amount.

Description: Specify a valid currency in the bill-balance call.

section/SHIPPING_ADDRESS_NOT_IN_RESIDENCE_COUNTRY 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.

section/SHP_INVALID_COUNTRY_CODE 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.

section/START_DATE_INVALID_FORMAT 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.

section/STATUS_INVALID 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.

section/SUBSCRIPTION_UNMAPPED_ERROR SUBSCRIPTION_UNMAPPED_ERROR

Message:

An internal error occurred.

Description: An internal error occurred.

section/TIME_TO_UPDATE_CLOSE_TO_BILLING_DATE 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.

section/TOKEN_NOT_FOUND TOKEN_NOT_FOUND

Message:

Internal error.

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

section/UNAUTHORIZED_AGREEMENT_REQUEST UNAUTHORIZED_AGREEMENT_REQUEST

Message:

You do not have permission to create this agreement.

Description: You are not authorized to create this agreement.

section/USR_BILLING_AGRMNT_NOT_ACTIVE USR_BILLING_AGRMNT_NOT_ACTIVE

Message:

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

Description: The merchant configuration is not valid.

section/VALIDATION_ERROR VALIDATION_ERROR

Message:

Invalid request - see details.

Description: Your request has a validation error.

section/WALLET_TOO_MANY_ATTEMPTS 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.

tag/Definitions Definitions

schema/agreement Agreement

The billing agreement information.


id	string<= 128 characters The PayPal-generated ID for the resource.
state	string<= 128 characters The state of the agreement. Value is: - `Pending`. The agreement awaits initial payment completion. - `Active`. The agreement is active and payments are scheduled. - `Suspended`. The agreement is suspended and payments are not scheduled until the agreement is reactivated. - `Cancelled`. The agreement is cancelled and payments are not scheduled. - `Expired`. The agreement is expired and no payments remain to be scheduled. Enum:"Pending""Active""Suspended""Cancelled""Expired"
description required	string<= 128 characters The agreement description.
start_date required	string<date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a `2017-01-02T14:36:21Z` start date and time for an account in the Berlin time zone (UTC + 1) to `2017-01-02T00:00:00`. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal `2017-01-02T00:00:00` start date and time becomes `2017-01-01T23:00:00` externally.
agreement_details	object (Agreement Details) The agreement details.
payer required	object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
override_merchant_preferences	object (Merchant Preferences) 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.
override_charge_models	Array of objects (Override Charge Model) 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.
plan required	object (Plan) The plan that can be used to create an agreement.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
shipping_address	object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address.

Copy

Expand allCollapse all

`{"id": "string",

"state": "Pending",

"description": "string",

"start_date": "2019-08-24T14:15:22Z",

"agreement_details": {"cycles_remaining": "string",

"cycles_completed": "string",

"next_billing_date": "string",

"last_payment_date": "string",

"final_payment_date": "string",

"failed_payment_count": "string",

"outstanding_balance": {"value": "string",

"currency": "string"

"last_payment_amount": {"value": "string",

"currency": "string"

}

"payer": {"payment_method": "bank",

"funding_instruments": [{"credit_card": {"id": "string",

"number": "string",

"type": "string",

"expire_month": 0,

"expire_year": 0,

"cvv2": 0,

"first_name": "string",

"last_name": "string",

"external_customer_id": "string",

"state": "expired",

"valid_until": "string",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

}

}

],

"funding_option_id": "string",

"payer_info": {"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"payer_id": "string",

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

"override_merchant_preferences": {"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

"override_charge_models": [{"charge_id": "string",

"amount": {"value": "string",

"currency": "string"

}

}

],

"plan": {"id": "string",

"name": "string",

"description": "string",

"type": "FIXED",

"state": "CREATED",

"create_time": "string",

"update_time": "string",

"payment_definitions": [{"id": "string",

"name": "string",

"type": "TRIAL",

"frequency_interval": "string",

"frequency": "WEEK",

"cycles": "string",

"charge_models": [{"id": "string",

"type": "TAX",

"amount": {"value": "string",

"currency": "string"

}

}

],

"amount": {"value": "string",

"currency": "string"

}

}

],

"terms": [{"id": "string",

"type": "MONTHLY",

"occurrences": "string",

"buyer_editable": "string",

"max_billing_amount": {"value": "string",

"currency": "string"

},

"amount_range": {"value": "string",

"currency": "string"

}

}

],

"merchant_preferences": {"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"currency_code": "string"

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/agreement_details Agreement Details

The agreement details.


cycles_remaining	string The number of payment cycles remaining for this agreement.
cycles_completed	string The number of payment cycles completed for this agreement.
next_billing_date	string The next billing date and time for this agreement, in Internet date and time format. For example, `2017-01-23T08:00:00Z`.
last_payment_date	string The last payment date and time for this agreement, in Internet date and time format. For example, `2016-12-23T08:00:00Z`.
final_payment_date	string The final payment date and time for this agreement, in Internet date and time format. For example, `2017-09-23T08:00:00Z`.
failed_payment_count	string The total number of failed payments for this agreement.
outstanding_balance	object (Currency) The currency and amount of the outstanding balance for this agreement.
last_payment_amount	object (Currency) The currency and amount of the last payment amount for this agreement.

Copy

Expand allCollapse all

`{"cycles_remaining": "string",

"cycles_completed": "string",

"next_billing_date": "string",

"last_payment_date": "string",

"final_payment_date": "string",

"failed_payment_count": "string",

"outstanding_balance": {"value": "string",

"currency": "string"

"last_payment_amount": {"value": "string",

"currency": "string"

}

schema/agreement_state_descriptor Agreement State Descriptor

The description of the current state of an agreement.


note	string<= 128 characters The reason for the agreement state change.

Copy

`{"note": "string"

schema/agreement_transaction Agreement Transaction

The agreement transaction.


transaction_id	string The ID of the transaction.
status	string The current status of the transaction. Value is: - `Completed`. The transaction is complete and the money has been transferred to the payee. - `Partially_Refunded`. A part of the transaction amount has been refunded to the payer. - `Pending`. The transaction is pending settlement. - `Refunded`. The transaction amount has been refunded to the payer. - `Denied`. The transaction has been denied. Enum:"Completed""Partially_Refunded""Pending""Refunded""Denied"
transaction_type	string The type of transaction. Typically, `Recurring Payment`.
payer_email	string The email ID of the customer.
payer_name	string The business name of the customer.
time_stamp	string The date and time when the transaction occurred, in Internet date and time format.
time_zone	string The time zone of the `update_time` field.
amount required	object (Currency) The currency and amount for a transaction.
fee_amount required	object (Currency) The currency and amount for a transaction.
net_amount required	object (Currency) The currency and amount for a transaction.

Copy

Expand allCollapse all

`{"transaction_id": "string",

"status": "Completed",

"transaction_type": "string",

"payer_email": "string",

"payer_name": "string",

"time_stamp": "string",

"time_zone": "string",

"amount": {"value": "string",

"currency": "string"

"fee_amount": {"value": "string",

"currency": "string"

"net_amount": {"value": "string",

"currency": "string"

}

schema/agreement_transactions Agreement Transactions

An array of agreement transactions.


agreement_transaction_list	Array of objects (Agreement Transaction) An array of agreement transactions.

Copy

Expand allCollapse all

`{"agreement_transaction_list": [{"transaction_id": "string",

"status": "Completed",

"transaction_type": "string",

"payer_email": "string",

"payer_name": "string",

"time_stamp": "string",

"time_zone": "string",

"amount": {"value": "string",

"currency": "string"

},

"fee_amount": {"value": "string",

"currency": "string"

},

"net_amount": {"value": "string",

"currency": "string"

}

}

]

schema/charge_models charge_model

The charge model for a payment definition. A charge model defines shipping fee and tax information.


id	string<= 128 characters The PayPal-generated ID for the resource.
type required	string<= 20 characters The charge model type. Enum:"TAX""SHIPPING"
amount required	object (Currency) The currency and amount for a transaction.

Copy

Expand allCollapse all

`{"id": "string",

"type": "TAX",

"amount": {"value": "string",

"currency": "string"

}

schema/country_code country_code

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

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

string<ppaas_common_country_code_v2> (country_code) = 2 characters^([A-Z]{2}|C2)$

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

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

Copy

"st"

schema/create_agreement_request Create Agreement Request

The billing agreement information.


id	string<= 128 characters The PayPal-generated ID for the resource.
state	string<= 128 characters The state of the agreement. Value is: - `Pending`. The agreement awaits initial payment completion. - `Active`. The agreement is active and payments are scheduled. - `Suspended`. The agreement is suspended and payments are not scheduled until the agreement is reactivated. - `Cancelled`. The agreement is cancelled and payments are not scheduled. - `Expired`. The agreement is expired and no more payments remain to be scheduled. Enum:"Pending""Active""Suspended""Cancelled""Expired"
name required	string<= 128 characters The agreement name.
description required	string<= 128 characters The agreement description.
start_date required	string<date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a `2017-01-02T14:36:21Z` start date and time for an account in the Berlin time zone (UTC + 1) to `2017-01-02T00:00:00`. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal `2017-01-02T00:00:00` start date and time becomes `2017-01-01T23:00:00` externally.
agreement_details	object (Agreement Details) The agreement details.
payer required	object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
override_merchant_preferences	object (Merchant Preferences) 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.
override_charge_models	Array of objects (Override Charge Model) 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.
plan required	object (Plan) The ID of the plan on which this agreement is based.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
shipping_address	object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address.

Copy

Expand allCollapse all

`{"id": "string",

"state": "Pending",

"name": "string",

"description": "string",

"start_date": "2019-08-24T14:15:22Z",

"agreement_details": {"cycles_remaining": "string",

"cycles_completed": "string",

"next_billing_date": "string",

"last_payment_date": "string",

"final_payment_date": "string",

"failed_payment_count": "string",

"outstanding_balance": {"value": "string",

"currency": "string"

"last_payment_amount": {"value": "string",

"currency": "string"

}

"payer": {"payment_method": "bank",

"funding_option_id": "string",

"payer_info": {"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"payer_id": "string",

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

"override_merchant_preferences": {"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

"override_charge_models": [{"charge_id": "string",

"amount": {"value": "string",

"currency": "string"

}

}

],

"plan": {"id": "string"

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/create_agreement_response Create Agreement Response

The billing agreement information.


id	string<= 128 characters The PayPal-generated ID for the resource.
state	string<= 128 characters The state of the agreement. Value is: - `Pending`. The agreement awaits initial payment completion. - `Active`. The agreement is active and payments are scheduled. - `Suspended`. The agreement is suspended and payments are not scheduled until the agreement is reactivated. - `Cancelled`. The agreement is cancelled and payments are not scheduled. - `Expired`. The agreement is expired and no more payments remain to be scheduled. Enum:"Pending""Active""Suspended""Cancelled""Expired"
name required	string<= 128 characters The agreement name.
description required	string<= 128 characters The agreement description.
start_date required	string<date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a `2017-01-02T14:36:21Z` start date and time for an account in the Berlin time zone (UTC + 1) to `2017-01-02T00:00:00`. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal `2017-01-02T00:00:00` start date and time becomes `2017-01-01T23:00:00` externally.
agreement_details	object (Agreement Details) The agreement details.
payer required	object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
override_merchant_preferences	object (Merchant Preferences) 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.
override_charge_models	Array of objects (Override Charge Model) 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.
plan required	object (Plan) The plan that can be used to create an agreement.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
shipping_address	object (Simple Postal Address (Coarse-Grained)) The shipping address of the agreement, which must be provided if it differs from the default address.

Copy

Expand allCollapse all

`{"id": "string",

"state": "Pending",

"name": "string",

"description": "string",

"start_date": "2019-08-24T14:15:22Z",

"agreement_details": {"cycles_remaining": "string",

"cycles_completed": "string",

"next_billing_date": "string",

"last_payment_date": "string",

"final_payment_date": "string",

"failed_payment_count": "string",

"outstanding_balance": {"value": "string",

"currency": "string"

"last_payment_amount": {"value": "string",

"currency": "string"

}

"payer": {"payment_method": "bank",

"funding_option_id": "string",

"payer_info": {"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"payer_id": "string",

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

"override_merchant_preferences": {"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

"override_charge_models": [{"charge_id": "string",

"amount": {"value": "string",

"currency": "string"

}

}

],

"plan": {"id": "string",

"name": "string",

"description": "string",

"type": "FIXED",

"state": "CREATED",

"create_time": "string",

"update_time": "string",

"merchant_preferences": {"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"currency_code": "string"

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"shipping_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/credit_card Credit Card

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


id	string The PayPal-generated ID for the resource.
number required	string The card number.
type required	string The card type. For example, Visa, MasterCard, and so on.
expire_month required	integer The two-digit card expiry month, in `MM` format. Value is from `01` to `12`.
expire_year required	integer The four-digit card expiry year, in `YYYY` format.
cvv2	integer The card validation code. Supported only when making a payment but not when saving a credit card for future use.
first_name	string The first name of the card holder.
last_name	string The last name of the card holder.
external_customer_id	string<= 256 characters 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	string The state of the funding instrument. Enum:"expired""ok"
valid_until	string The date and time when the credit card becomes unusable from the vault, in Internet date and time format. The `valid_until` parameter is not the same as the expiration month and year. The expiration month and year might be later than the `valid_until` date. For example, the card expires in November 2019 but the `valid_until` date is October 17th, 2019.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
billing_address	object (Simple Postal Address (Coarse-Grained)) A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.

Copy

Expand allCollapse all

`{"id": "string",

"number": "string",

"type": "string",

"expire_month": 0,

"expire_year": 0,

"cvv2": 0,

"first_name": "string",

"last_name": "string",

"external_customer_id": "string",

"state": "expired",

"valid_until": "string",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/currency Currency

The currency and amount for a transaction.


value required	string<= 32 characters^((-?[0-9]+)\|(-?([0-9]+)?[.][0-9]+))$ 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.
currency required	string<ppaas_common_currency_code_v2> (currency_code) = 3 characters The three-character ISO-4217 currency code that identifies the currency.

Copy

`{"value": "string",

"currency": "string"

schema/currency_code currency_code

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

string<ppaas_common_currency_code_v2> (currency_code) = 3 characters

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

Copy

"str"

schema/error Error

The error information.


name required	string The human-readable, unique name of the error.
debug_id	string The PayPal internal ID. Used for correlation purposes.
message required	string The message that describes the error.
information_link required	string The URI to detailed information related to this error for the developer.
details	Array of objects (Error Details) An array of additional details for the error.

Copy

Expand allCollapse all

`{"name": "string",

"debug_id": "string",

"message": "string",

"information_link": "string",

"details": [{"field": "string",

"issue": "string"

}

]

schema/error_details Error Details

The error details. Required for client-side 4XX errors.


field required	string The name of the field that caused the error.
issue required	string The reason for the error.

Copy

`{"field": "string",

"issue": "string"

schema/funding_instrument Funding Instrument

The customer's funding instrument that can be used to fund a payment.


credit_card	object (Credit Card) The credit card that can be used to fund a payment.

Copy

Expand allCollapse all

`{"credit_card": {"id": "string",

"number": "string",

"type": "string",

"expire_month": 0,

"expire_year": 0,

"cvv2": 0,

"first_name": "string",

"last_name": "string",

"external_customer_id": "string",

"state": "expired",

"valid_until": "string",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/link_description Link Description

The request-related HATEOAS link information.


href required	string The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel required	string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method	string The HTTP method required to make the related call. Enum:"GET""POST""PUT""DELETE""HEAD""CONNECT""OPTIONS""PATCH"

Copy

`{"href": "string",

"rel": "string",

"method": "GET"

schema/merchant_preferences Merchant Preferences

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.


id	string<= 128 characters The PayPal-generated ID for the resource.
cancel_url required	string<uri><= 1000 characters The URL to which the customer is redirected if they cancel the agreement.
return_url required	string<uri><= 1000 characters The URL to which the customer is redirected if they accept the agreement.
max_fail_attempts	string The maximum number of allowed failed payment attempts. Default is `0`, which allows infinite failed payment attempts.
auto_bill_amount	string Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is: - `NO`. PayPal does not automatically bill the customer the outstanding balance. Default is `NO`. - `YES`. PayPal automatically bills the customer the outstanding balance. Enum:"YES""NO"
initial_fail_amount_action	string Default:"CONTINUE" The action if the customer's initial payment fails. Value is: - `CONTINUE`. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle. - `CANCEL`. PayPal creates the agreement but sets its state to pending until the initial payment clears. When the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is cancelled. > Note: Initial payment failures will not increment the `max_fail_attempt` counter as initial payments are not considered regularly recurring payments. Enum:"CONTINUE""CANCEL"
accepted_payment_type	string The payment types that are accepted for this agreement. Read-only and reserved for future use.
char_set	string The character set for this agreement. Read-only and reserved for future use.
setup_fee	object (Currency) The currency and amount for a transaction.

Copy

Expand allCollapse all

`{"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

schema/override_charge_model Override Charge Model

The charge model that overrides default charge information during agreement creation.


charge_id required	string The ID of the charge model.
amount required	object (Currency) The currency and amount for a transaction.

Copy

Expand allCollapse all

`{"charge_id": "string",

"amount": {"value": "string",

"currency": "string"

}

schema/patch Patch

The JSON patch object to apply partial updates to resources.

| op
required | string

The operation.

Enum Value	Description
add	Depending on the target location reference, completes one of these functions: - The target location is an array index. Inserts a new value into the array at the specified index. - The target location is an object parameter that does not already exist. Adds a new parameter to the object. - The target location is an object parameter that does exist. Replaces that parameter's value. The `value` parameter defines the value to add. For more information, see 4.1. add.
remove	Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace	Replaces the value at the target location with a new value. The operation object must contain a `value` parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move	Removes the value at a specified location and adds it to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the `from` location must exist. For more information, see 4.4. move.
copy	Copies the value at a specified location to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the `from` location must exist. For more information, see 4.5. copy.
test	Tests that a value at the target location is equal to a specified value. The operation object must contain a `value` parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the `value` value. For test, `equal` indicates that the value at the target location and the value that `value` defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain 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.
objects	Contain 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.

Copy

Expand allCollapse all

`{"op": "add",

"path": "string",

"value": { },

"from": "string"

schema/patch_request Patch Request

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

Array

| op
required | string

The operation.

Enum Value	Description
add	Depending on the target location reference, completes one of these functions: - The target location is an array index. Inserts a new value into the array at the specified index. - The target location is an object parameter that does not already exist. Adds a new parameter to the object. - The target location is an object parameter that does exist. Replaces that parameter's value. The `value` parameter defines the value to add. For more information, see 4.1. add.
remove	Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace	Replaces the value at the target location with a new value. The operation object must contain a `value` parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move	Removes the value at a specified location and adds it to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the `from` location must exist. For more information, see 4.4. move.
copy	Copies the value at a specified location to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the `from` location must exist. For more information, see 4.5. copy.
test	Tests that a value at the target location is equal to a specified value. The operation object must contain a `value` parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the `value` value. For test, `equal` indicates that the value at the target location and the value that `value` defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain 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.
objects	Contain 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.

Copy

Expand allCollapse all

[{"op": "add",\ \ "path": "string",\ \ "value": { },\ \ "from": "string"\ \ }\ \ ]

schema/payer Payer

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


payment_method required	string The payment method. Enum:"bank""paypal"
funding_instruments	Array of objects (Funding Instrument) An array of funding instruments.
funding_option_id	string The ID of the customer-selected funding option for the payment. Value is `funding_instruments` or `funding_option_id`.
payer_info	object (Payer Information) The payer information.

Copy

Expand allCollapse all

`{"payment_method": "bank",

"funding_option_id": "string",

"payer_info": {"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"payer_id": "string",

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/payer_info Payer Information

The payer information.


email	string<email> The payer's email address.
first_name	string The payer's first name.
last_name	string The payer's last name.
payer_id	string The PayPal-assigned ID for the payer.
shipping_address	object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address.
billing_address	object (Simple Postal Address (Coarse-Grained)) A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.

Copy

Expand allCollapse all

`{"email": "user@example.com",

"first_name": "string",

"last_name": "string",

"payer_id": "string",

"shipping_address": {"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

"billing_address": {"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

}

schema/payment_definition Payment Definition

The payment definition, which defines a regular or trial payment.

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.

Enum Value	Description
WEEK	The payment is weekly.
DAY	The payment is daily.
YEAR	The payment is yearly.
MONTH	The payment is monthly.
cycles required	string The number of payment cycles in this definition. For infinite plans with a regular payment definition, set `cycles` to `0`.
charge_models	Array of objects (charge_model) An array of shipping fee and tax information for this definition.
amount required	object (Currency) The currency and amount for a transaction.

Copy

Expand allCollapse all

`{"id": "string",

"name": "string",

"type": "TRIAL",

"frequency_interval": "string",

"frequency": "WEEK",

"cycles": "string",

"charge_models": [{"id": "string",

"type": "TAX",

"amount": {"value": "string",

"currency": "string"

}

}

],

"amount": {"value": "string",

"currency": "string"

}

schema/plan Plan

The plan that can be used to create an agreement.


id	string<= 128 characters The PayPal-generated ID for the resource.
name required	string<= 128 characters The plan name.
description required	string<= 128 characters The plan description.
type required	string<= 20 characters The plan type. Enum:"FIXED""INFINITE"
state	string The status of the plan. Enum:"CREATED""ACTIVE""INACTIVE""DELETED"
create_time	string The date and time when the plan was created, in Internet date and time format.
update_time	string The date and time when this plan was updated, in Internet date and time format.
payment_definitions	Array of objects (Payment Definition) An array of payment definitions for this plan.
terms	Array of objects (Terms) An array of terms for this plan.
merchant_preferences	object (Merchant Preferences) 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.
links	Array of objects (Link Description) An array of request-related HATEOAS links.
currency_code	string<ppaas_common_currency_code_v2> (currency_code) = 3 characters The currency code for the plan.

Copy

Expand allCollapse all

`{"id": "string",

"name": "string",

"description": "string",

"type": "FIXED",

"state": "CREATED",

"create_time": "string",

"update_time": "string",

"merchant_preferences": {"id": "string",

"cancel_url": "http://example.com",

"return_url": "http://example.com",

"max_fail_attempts": "string",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"value": "string",

"currency": "string"

}

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"currency_code": "string"

schema/shipping_address Shipping Address

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


recipient_name	string The name of the recipient at this address.
default_address	boolean The default shipping address of the payer.
line1 required	string The first line of the address. For example, number or street.
line2	string The second line of the address. For example, suite or apartment number.
city required	string The city name.
state	string The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
country_code required	string<ppaas_common_country_code_v2> (country_code) = 2 characters^([A-Z]{2}\|C2)$ The two-character ISO 3166-1 code that identifies the country or region. > Note: The country code for Great Britain is `GB` and not `UK` as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_code	string The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

Copy

`{"recipient_name": "string",

"default_address": true,

"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

schema/address Simple Postal Address (Coarse-Grained)

A simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.


line1 required	string The first line of the address. For example, number or street.
line2	string The second line of the address. For example, suite or apartment number.
city required	string The city name.
state	string The code for a US state or the equivalent for other countries. Required for transactions if the address is in one of these countries: Argentina, Brazil, Canada, China, India, Italy, Japan, Mexico, Thailand, or United States. Maximum length is 40 single-byte characters.
country_code required	string<ppaas_common_country_code_v2> (country_code) = 2 characters^([A-Z]{2}\|C2)$ The two-character ISO 3166-1 code that identifies the country or region. > Note: The country code for Great Britain is `GB` and not `UK` as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_code	string The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

Copy

`{"line1": "string",

"line2": "string",

"city": "string",

"state": "string",

"country_code": "st",

"postal_code": "string"

schema/terms Terms

The plan terms.

The term type.

Enum Value	Description
MONTHLY	The term is monthly.
WEEKLY	The term is weekly.
YEARLY	The term is yearly.
occurrences required	string The number of times that money can be pulled during this term.
buyer_editable required	string Indicates whether the customer can edit the amount in this term.
max_billing_amount required	object (Currency) The currency and amount for a transaction.
amount_range required	object (Currency) The currency and amount for a transaction.

Copy

Expand allCollapse all

`{"id": "string",

"type": "MONTHLY",

"occurrences": "string",

"buyer_editable": "string",

"max_billing_amount": {"value": "string",

"currency": "string"

"amount_range": {"value": "string",

"currency": "string"

}

Billing Agreements(1) ​

operation/billing-agreements.post Create agreement ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.agreement-execute Execute agreement ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.get Show agreement details ​

path Parameters ​

operation/billing-agreements.patch Update agreement ​

path Parameters ​

Request Body schema: application/json ​

operation/billing-agreements.suspend Suspend agreement ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.re-activate Reactivate agreement ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.cancel Cancel agreement ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.bill-balance Bill agreement balance ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.set-balance Set agreement balance ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-agreements.transactions List agreement transactions ​

path Parameters ​

query Parameters ​

tag/Errors Errors ​

section/ACCOUNT_RESTRICTED ACCOUNT_RESTRICTED ​

section/ADDRESS_INVALID ADDRESS_INVALID ​

section/BA_TOKEN BA_TOKEN ​

section/BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE ​

section/BUSADD_STATE_UNSUPPORTED BUSADD_STATE_UNSUPPORTED ​

section/CALL_FAILED_PAYMENT CALL_FAILED_PAYMENT ​

section/CANNOT_FIND_PROFILE_DESC CANNOT_FIND_PROFILE_DESC ​

section/CANNOT_MIX_CURRENCIES CANNOT_MIX_CURRENCIES ​

section/CANT_INCREASE_OUTSTANDING_AMOUNT CANT_INCREASE_OUTSTANDING_AMOUNT ​

section/CC_STATUS_INVALID CC_STATUS_INVALID ​

section/CC_TYPE_NOT_SUPPORTED CC_TYPE_NOT_SUPPORTED ​

section/DPRP_DISABLED DPRP_DISABLED ​

section/DUPLICATE_REQUEST_ID DUPLICATE_REQUEST_ID ​

section/EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED ​

section/EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN ​

section/FEATURE_DISABLED FEATURE_DISABLED ​

section/FEATURE_NOT_AVAILABLE FEATURE_NOT_AVAILABLE ​

section/GATEWAY_DECLINE_CVV2 GATEWAY_DECLINE_CVV2 ​

section/INTERNAL_ERROR INTERNAL_ERROR ​

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR ​

section/INVALID_AMOUNT INVALID_AMOUNT ​

section/INVALID_ARGS INVALID_ARGS ​

section/INVALID_CC_NUMBER INVALID_CC_NUMBER ​

section/INVALID_CURRENCY INVALID_CURRENCY ​

section/INVALID_ID_PASSED INVALID_ID_PASSED ​

section/INVALID_PROFILE_ACTION INVALID_PROFILE_ACTION ​

section/INVALID_PROFILE_ID INVALID_PROFILE_ID ​

section/INVALID_PROFILE_STATUS INVALID_PROFILE_STATUS ​

section/INVALID_SECURITY_CTX INVALID_SECURITY_CTX ​

section/INVALID_STATUS_TO_CANCEL INVALID_STATUS_TO_CANCEL ​

section/INVALID_STATUS_TO_REACTIVATE INVALID_STATUS_TO_REACTIVATE ​

section/INVALID_STATUS_TO_SUSPEND INVALID_STATUS_TO_SUSPEND ​

section/INVALID_TOKEN INVALID_TOKEN ​

section/MALFORMED_REQUEST MALFORMED_REQUEST ​

section/MERCHANT_ACCOUNT_DENIED MERCHANT_ACCOUNT_DENIED ​

section/MERCHANT_COUNTRY_NOT_SUPPORTED MERCHANT_COUNTRY_NOT_SUPPORTED ​

section/MERCHANT_ID_NOT_AUTHORIZED MERCHANT_ID_NOT_AUTHORIZED ​

section/MISSING_CVV2 MISSING_CVV2 ​

section/OUTSTANDING_PAYMENT_ALREADY_SCHEDULED OUTSTANDING_PAYMENT_ALREADY_SCHEDULED ​

section/PAYER_ACCOUNT_DENIED PAYER_ACCOUNT_DENIED ​

section/PAYER_COUNTRY_NOT_SUPPORTED PAYER_COUNTRY_NOT_SUPPORTED ​

section/PAYMENT_METHOD PAYMENT_METHOD ​

section/PLAN_TYPE PLAN_TYPE ​

section/PROCESSOR_DECLINE_INVALID_CC_COUNTRY PROCESSOR_DECLINE_INVALID_CC_COUNTRY ​

section/RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS ​

section/REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED ​

section/REFUSED_MARK_REF_TXN_NOT_ENABLED REFUSED_MARK_REF_TXN_NOT_ENABLED ​

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING ​

section/RT_AGREEMENT_ALREADY_CANCELED RT_AGREEMENT_ALREADY_CANCELED ​

section/RT_INVALID_AGREEMENT_ID RT_INVALID_AGREEMENT_ID ​

Billing Agreements(1)

operation/billing-agreements.post Create agreement

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.agreement-execute Execute agreement

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.get Show agreement details

path Parameters

operation/billing-agreements.patch Update agreement

path Parameters

Request Body schema: application/json

operation/billing-agreements.suspend Suspend agreement

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.re-activate Reactivate agreement

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.cancel Cancel agreement

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.bill-balance Bill agreement balance

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.set-balance Set agreement balance

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-agreements.transactions List agreement transactions

path Parameters

query Parameters

tag/Errors Errors

section/ACCOUNT_RESTRICTED ACCOUNT_RESTRICTED

section/ADDRESS_INVALID ADDRESS_INVALID

section/BA_TOKEN BA_TOKEN

section/BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE BILL_AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE

section/BUSADD_STATE_UNSUPPORTED BUSADD_STATE_UNSUPPORTED

section/CALL_FAILED_PAYMENT CALL_FAILED_PAYMENT

section/CANNOT_FIND_PROFILE_DESC CANNOT_FIND_PROFILE_DESC

section/CANNOT_MIX_CURRENCIES CANNOT_MIX_CURRENCIES

section/CANT_INCREASE_OUTSTANDING_AMOUNT CANT_INCREASE_OUTSTANDING_AMOUNT

section/CC_STATUS_INVALID CC_STATUS_INVALID

section/CC_TYPE_NOT_SUPPORTED CC_TYPE_NOT_SUPPORTED

section/DPRP_DISABLED DPRP_DISABLED

section/DUPLICATE_REQUEST_ID DUPLICATE_REQUEST_ID

section/EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED EXECUTE_AGREEMENT_BUYER_NOT_ACCEPTED

section/EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN EXECUTE_AGREEMENT_DOES_NOT_OWN_TOKEN

section/FEATURE_DISABLED FEATURE_DISABLED

section/FEATURE_NOT_AVAILABLE FEATURE_NOT_AVAILABLE

section/GATEWAY_DECLINE_CVV2 GATEWAY_DECLINE_CVV2

section/INTERNAL_ERROR INTERNAL_ERROR

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR

section/INVALID_AMOUNT INVALID_AMOUNT

section/INVALID_ARGS INVALID_ARGS

section/INVALID_CC_NUMBER INVALID_CC_NUMBER

section/INVALID_CURRENCY INVALID_CURRENCY

section/INVALID_ID_PASSED INVALID_ID_PASSED

section/INVALID_PROFILE_ACTION INVALID_PROFILE_ACTION

section/INVALID_PROFILE_ID INVALID_PROFILE_ID

section/INVALID_PROFILE_STATUS INVALID_PROFILE_STATUS

section/INVALID_SECURITY_CTX INVALID_SECURITY_CTX

section/INVALID_STATUS_TO_CANCEL INVALID_STATUS_TO_CANCEL

section/INVALID_STATUS_TO_REACTIVATE INVALID_STATUS_TO_REACTIVATE

section/INVALID_STATUS_TO_SUSPEND INVALID_STATUS_TO_SUSPEND

section/INVALID_TOKEN INVALID_TOKEN

section/MALFORMED_REQUEST MALFORMED_REQUEST

section/MERCHANT_ACCOUNT_DENIED MERCHANT_ACCOUNT_DENIED

section/MERCHANT_COUNTRY_NOT_SUPPORTED MERCHANT_COUNTRY_NOT_SUPPORTED

section/MERCHANT_ID_NOT_AUTHORIZED MERCHANT_ID_NOT_AUTHORIZED

section/MISSING_CVV2 MISSING_CVV2

section/OUTSTANDING_PAYMENT_ALREADY_SCHEDULED OUTSTANDING_PAYMENT_ALREADY_SCHEDULED

section/PAYER_ACCOUNT_DENIED PAYER_ACCOUNT_DENIED

section/PAYER_COUNTRY_NOT_SUPPORTED PAYER_COUNTRY_NOT_SUPPORTED

section/PAYMENT_METHOD PAYMENT_METHOD

section/PLAN_TYPE PLAN_TYPE

section/PROCESSOR_DECLINE_INVALID_CC_COUNTRY PROCESSOR_DECLINE_INVALID_CC_COUNTRY

section/RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS RECURRING_PAYMENT_SCHEDULED_WITHIN_24HOURS

section/REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED

section/REFUSED_MARK_REF_TXN_NOT_ENABLED REFUSED_MARK_REF_TXN_NOT_ENABLED

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING

section/RT_AGREEMENT_ALREADY_CANCELED RT_AGREEMENT_ALREADY_CANCELED

section/RT_INVALID_AGREEMENT_ID RT_INVALID_AGREEMENT_ID