Billing Agreements API
Important: The use of the PayPal REST /payments
APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.
Note: The Billing Agreements API does not support the payee
object.
Billing agreements (resource group)
/billing-agreements
resource to create, update, show details for, bill the balance for, cancel, reactivate, set the balance for, suspend, list transactions for, and execute agreements.
Create agreement
agreement
object with the name, description, start date, ID of the plan on which to base the agreement, and customer and shipping address information.
Request body
-
name
string
required
The agreement name. -
description
string
required
The agreement description. -
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
-
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
The ID of the plan on which this agreement is based.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"name": "Override Agreement",
"description": "PayPal payment agreement that overrides merchant preferences and shipping fee and tax information.",
"start_date": "2017-12-22T09:13:49Z",
"payer": {
"payment_method": "paypal",
"payer_info": {
"email": "payer@example.com"
}
},
"plan": {
"id": "P-1WJ68935LL406420PUTENA2I"
},
"shipping_address": {
"line1": "Hotel Staybridge",
"line2": "Crooke Street",
"city": "San Jose",
"state": "CA",
"postal_code": "95112",
"country_code": "US"
},
"override_merchant_preferences": {
"setup_fee": {
"value": "3",
"currency": "GBP"
},
"return_url": "https://example.com/",
"cancel_url": "https://example.com/cancel",
"auto_bill_amount": "YES",
"initial_fail_amount_action": "CONTINUE",
"max_fail_attempts": "11"
},
"override_charge_models": [
{
"charge_id": "CHM-8373958130821962WUTENA2Q",
"amount": {
"value": "1",
"currency": "GBP"
}
}
]
}'
Response
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.-
id
string
The PayPal-generated ID for the resource. -
state
enum
The state of the agreement. Value is:Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no more payments remain to be scheduled.
-
name
string
The agreement name. -
description
string
The agreement description. -
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
payer
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. -
shipping_address
The shipping address of the agreement, which must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
plan
The plan that can be used to create an agreement. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"name": "Override Agreement",
"description": "Agreement that overrides merchant preferences and charge models",
"payer": {
"payment_method": "paypal",
"payer_info": {
"email": "payer@example.com"
}
},
"plan": {
"id": "P-1WJ68935LL406420PUTENA2I",
"state": "ACTIVE",
"name": "Fast Speed Plan",
"description": "Vanilla plan",
"type": "INFINITE",
"payment_definitions": [
{
"id": "PD-9WG6983719571780GUTENA2I",
"name": "Regular payment definition",
"type": "REGULAR",
"frequency": "DAY",
"amount": {
"currency": "GBP",
"value": "10"
},
"charge_models": [
{
"id": "CHM-8373958130821962WUTENA2Q",
"type": "SHIPPING",
"amount": {
"currency": "GBP",
"value": "1"
}
},
{
"id": "CHM-2937144979861454NUTENA2Q",
"type": "TAX",
"amount": {
"currency": "GBP",
"value": "2"
}
}
],
"cycles": "0",
"frequency_interval": "1"
},
{
"id": "PD-89M493313S710490TUTENA2Q",
"name": "Trial payment definition",
"type": "TRIAL",
"frequency": "MONTH",
"amount": {
"currency": "GBP",
"value": "100"
},
"charge_models": [
{
"id": "CHM-78K47820SS4923826UTENA2Q",
"type": "SHIPPING",
"amount": {
"currency": "GBP",
"value": "10"
}
},
{
"id": "CHM-9M366179U7339472RUTENA2Q",
"type": "TAX",
"amount": {
"currency": "GBP",
"value": "12"
}
}
],
"cycles": "5",
"frequency_interval": "2"
}
],
"merchant_preferences": {
"setup_fee": {
"currency": "GBP",
"value": "3"
},
"max_fail_attempts": "11",
"return_url": "https://example.com/",
"cancel_url": "https://example.com/cancel",
"auto_bill_amount": "YES",
"initial_fail_amount_action": "CONTINUE"
}
},
"links": [
{
"href": "https://api.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-83C745436S346813F",
"rel": "approval_url",
"method": "REDIRECT"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/EC-83C745436S346813F/agreement-execute",
"rel": "execute",
"method": "POST"
}
],
"start_date": "2017-12-22T09:13:49Z"
}
Update agreement
Path parameters
-
agreement_id
string
required
The ID of the agreement to update.
Request body
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
Sample Request
curl -v -X PATCH https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "replace",
"path": "/",
"value": {
"description": "Updated description.",
"start_date": "2017-12-22T09:13:49Z",
"shipping_address": {
"line1": "Hotel Blue Diamond",
"line2": "Church Street",
"city": "San Jose",
"state": "CA",
"postal_code": "95112",
"country_code": "US"
}
}
}
]'
Response
200 OK
status code with no JSON response body.Sample Response
200 OK
Show agreement details
Path parameters
-
agreement_id
string
required
The ID of the agreement for which to show details.
Response
200 OK
status code and a JSON response body that shows billing agreement details.-
id
string
The PayPal-generated ID for the resource. -
state
enum
The state of the agreement. Value is:Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no payments remain to be scheduled.
-
description
string
The agreement description. -
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
payer
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. -
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
plan
The plan that can be used to create an agreement. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"id": "I-1TJ3GAGG82Y9",
"state": "Active",
"description": "Monthly agreement with free trial payment definition.",
"payer": {
"payment_method": "paypal",
"status": "unverified",
"payer_info": {
"email": "johndoe@example.com",
"first_name": "John",
"last_name": "Doe",
"payer_id": "NEW8A85AK4ET4",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
}
}
},
"plan": {
"name": "Plan with Regular and Trial Payment Definitions",
"description": "Plan with regular and trial payment definitions.",
"type": "FIXED",
"payment_definitions": [
{
"name": "Trial payment definition",
"type": "TRIAL",
"frequency": "MONTH",
"amount": {
"value": "0.00",
"currency": "USD"
},
"cycles": "2",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.00",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.00",
"currency": "USD"
}
}
],
"frequency_interval": "1"
},
{
"name": "Regular payment definition",
"type": "REGULAR",
"frequency": "MONTH",
"amount": {
"value": "5.99",
"currency": "USD"
},
"cycles": "10",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.29",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.20",
"currency": "USD"
}
}
],
"frequency_interval": "1"
}
],
"merchant_preferences": {
"setup_fee": {
"value": "0.40",
"currency": "USD"
},
"return_url": "https://example.com",
"cancel_url": "https://example.com/cancel",
"max_fail_attempts": "2",
"auto_bill_amount": "YES"
},
"links": [],
"currency_code": "USD"
},
"start_date": "2016-12-23T08:00:00Z",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
},
"agreement_details": {
"outstanding_balance": {
"currency": "USD",
"value": "0.00"
},
"cycles_remaining": "2",
"cycles_completed": "0",
"next_billing_date": "2017-01-23T08:00:00Z",
"last_payment_date": "2016-12-23T08:00:00Z",
"last_payment_amount": {
"currency": "USD",
"value": "0.40"
},
"final_payment_date": "2017-09-23T08:00:00Z",
"failed_payment_count": "0"
},
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend",
"rel": "suspend",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/reactivate",
"rel": "re_activate",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance",
"rel": "self",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance",
"rel": "self",
"method": "POST"
}
]
}
Bill agreement balance
Path parameters
-
agreement_id
string
required
The ID of the agreement for which to bill the balance.
Request body
-
note
string
The reason for the agreement state change.
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Cancel agreement
agreement_state_descriptor
object with an optional note that describes the reason for the cancellation and the agreement amount and currency.
Path parameters
-
agreement_id
string
required
The ID of the agreement to cancel.
Request body
-
note
string
The reason for the agreement state change.
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Reactivate agreement
agreement_state_descriptor
object with with a note that describes the reason for the reactivation and the agreement amount and currency.
Path parameters
-
agreement_id
string
required
The ID of the agreement to reactivate.
Request body
-
note
string
The reason for the agreement state change.
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Set agreement balance
Path parameters
-
agreement_id
string
required
The ID of the agreement for which to set a balance.
Request body
-
The three-character ISO-4217 currency code that identifies the currency.
-
value
string
required
The currency value. Might be an integer for currencies likeJPY
that are not typically fractional or a three-place decimal fraction for currencies likeTND
that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Suspend agreement
Path parameters
-
agreement_id
string
required
The ID of the agreement to suspend.
Request body
-
note
string
The reason for the agreement state change.
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
List agreement transactions
Path parameters
-
agreement_id
string
required
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.
Response
200 OK
status code and a JSON response body that lists transactions with details.-
agreement_transaction_list
array (contains the agreement_transaction object)
An array of agreement transactions.
Sample Response
{
"agreement_transaction_list": [
{
"transaction_id": "I-V8SSE9WLJGY6",
"status": "Completed",
"transaction_type": "Recurring Payment",
"amount": {
"value": "100",
"currency": "USD"
},
"fee_amount": {
"value": "1",
"currency": "USD"
},
"net_amount": {
"value": "100",
"currency": "USD"
},
"payer_email": "",
"payer_name": " ",
"time_stamp": "2017-06-16T13:46:53Z",
"time_zone": "GMT"
},
{
"transaction_id": "I-V8SSE9WLJGY6",
"status": "Denied",
"transaction_type": "Recurring Payment",
"amount": {
"value": "100",
"currency": "USD"
},
"fee_amount": {
"value": "1",
"currency": "USD"
},
"net_amount": {
"value": "100",
"currency": "USD"
},
"payer_email": "",
"payer_name": " ",
"time_stamp": "2017-06-16T13:52:26Z",
"time_zone": "GMT"
},
{
"transaction_id": "I-V8SSE9WLJGY6",
"status": "Pending",
"transaction_type": "Recurring Payment",
"amount": {
"value": "100",
"currency": "USD"
},
"fee_amount": {
"value": "1",
"currency": "USD"
},
"net_amount": {
"value": "100",
"currency": "USD"
},
"payer_email": "",
"payer_name": " ",
"time_stamp": "2017-06-16T14:00:23Z",
"time_zone": "GMT"
},
{
"transaction_id": "I-V8SSE9WLJGY6",
"status": "Denied",
"transaction_type": "Recurring Payment",
"amount": {
"value": "100",
"currency": "USD"
},
"fee_amount": {
"value": "1",
"currency": "USD"
},
"net_amount": {
"value": "100",
"currency": "USD"
},
"payer_email": "",
"payer_name": " ",
"time_stamp": "2017-06-16T14:02:54Z",
"time_zone": "GMT"
}
]
}
Execute agreement
Path parameters
-
payment_token
string
required
The ID of the agreement to execute.
Response
200 OK
status code and a JSON response body that shows billing agreement details.-
id
string
The PayPal-generated ID for the resource. -
state
enum
The state of the agreement. Value is:Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no payments remain to be scheduled.
-
description
string
The agreement description. -
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
payer
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. -
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
plan
The plan that can be used to create an agreement. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"id": "I-1TJ3GAGG82Y9",
"state": "Active",
"description": "Monthly agreement with free trial payment definition.",
"payer": {
"payment_method": "paypal",
"status": "unverified",
"payer_info": {
"email": "johndoe@example.com",
"first_name": "John",
"last_name": "Doe",
"payer_id": "NEW8A85AK4ET4",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
}
}
},
"plan": {
"name": "Plan with Regular and Trial Payment Definitions",
"description": "Plan with regular and trial payment definitions.",
"type": "FIXED",
"payment_definitions": [
{
"name": "Trial payment definition",
"type": "TRIAL",
"frequency": "MONTH",
"amount": {
"value": "0.00",
"currency": "USD"
},
"cycles": "2",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.00",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.00",
"currency": "USD"
}
}
],
"frequency_interval": "1"
},
{
"name": "Regular payment definition",
"type": "REGULAR",
"frequency": "MONTH",
"amount": {
"value": "5.99",
"currency": "USD"
},
"cycles": "10",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.29",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.20",
"currency": "USD"
}
}
],
"frequency_interval": "1"
}
],
"merchant_preferences": {
"setup_fee": {
"value": "0.40",
"currency": "USD"
},
"return_url": "https://example.com",
"cancel_url": "https://example.com/cancel",
"max_fail_attempts": "2",
"auto_bill_amount": "YES"
},
"links": [],
"currency_code": "USD"
},
"start_date": "2016-12-23T08:00:00Z",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
},
"agreement_details": {
"outstanding_balance": {
"value": "0.00",
"currency": "USD"
},
"cycles_remaining": "2",
"cycles_completed": "0",
"next_billing_date": "2017-01-23T08:00:00Z",
"last_payment_date": "2016-12-23T08:00:00Z",
"last_payment_amount": {
"value": "0.40",
"currency": "USD"
},
"final_payment_date": "2017-09-23T08:00:00Z",
"failed_payment_count": "0"
},
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
address
-
line1
string
required
The first line of the address. For example, number or street. -
line2
string
The second line of the address. For example, suite or apartment number. -
city
string
required
The city name. -
state
string
-
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
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.
agreement
-
id
string
The PayPal-generated ID for the resource. -
state
enum
The state of the agreement. Value is:Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no payments remain to be scheduled.
-
description
string
required
The agreement description. -
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
-
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
The plan that can be used to create an agreement.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
agreement_details
-
outstanding_balance
The currency and amount of the outstanding balance for this agreement. -
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
. -
last_payment_amount
The currency and amount of the last payment amount for this agreement. -
final_payment_date
string
The final payment date and time for this agreement, in Internet date and time format. For example,2017-09-23T08:00:00Z
. -
failed_payment_count
string
The total number of failed payments for this agreement.
agreement_state_descriptor
-
note
string
The reason for the agreement state change.
agreement_transaction
-
transaction_id
string
The ID of the transaction. -
status
enum
The current status of the transaction. Value is:Completed
. The transaction is complete and the money has been transferred to the payee.Partially_Refunded
. A part of the transaction amount has been refunded to the payer.Pending
. The transaction is pending settlement.Refunded
. The transaction amount has been refunded to the payer.Denied
. The transaction has been denied.
-
transaction_type
string
The type of transaction. Typically,Recurring Payment
. -
The currency and amount of the transaction.
-
The currency and amount of the transaction fee.
-
The currency and amount of the transaction net amount.
-
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 theupdate_time
field.
agreement_transactions
-
agreement_transaction_list
array (contains the agreement_transaction object)
An array of agreement transactions.
bank_account
-
id
string
The PayPal-generated ID for the resource. -
account_number
string
required
The account number in international bank account number (IBAN) format or basic bank account number (BBAN) format. The maximum length for the IBAN format is 34 characters. The maximum length for the BBAN format is 17 characters. -
account_number_type
enum
required
The type of bank account number. A valid value is basic bank account number (BBAN) or international bank account number (IBAN). For more information, see International Bank Account Number. -
routing_number
string
The routing transit number, or bank code, of the bank. Typically, you specify this value for domestic use only. International bank account numbers (IBAN) include the bank code. For more information, see Bank code. -
account_type
enum
The bank account type. -
account_name
string
A customer-designated account name. -
check_type
enum
The check type when the information was obtained from the facilitator or merchant. -
auth_type
enum
The authorization type, which indicates how the check was obtained from the customer if a check is the source of information. -
auth_capture_timestamp
string
The date and time when the authorization was captured, in Internet date and time format. Use this parameter if you must capture the user authorization due to any privacy requirements. -
bank_name
string
The bank name. -
country_code
string
The two-letter country code of the bank. -
first_name
string
The account holder's first name. -
last_name
string
The account holder's last name. -
birth_date
string
The account holder's birth date. -
billing_address
The billing address. -
state
enum
The state of this funding instrument. -
confirmation_status
enum
The confirmation status of a bank account. -
payer_id
string
Deprecated. Instead, use theexternal_customer_id
parameter. -
external_customer_id
string
The facilitator-generated ID for the customer who owns this bank account. Required when you create or use a vaulted funding instrument. -
merchant_id
string
The facilitator-generated ID for the merchant for whom the bank account was vaulted that can be used to restrict usage of the bank account to the merchant. -
create_time
string
The date and time when the bank account was created, in Internet date and time format. -
update_time
string
The date and time when the bank account was last updated, in Internet date and time format. -
valid_until
string
The date and time after which the bank account can no longer be used to fund a payment, in Internet date and time format. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
charge_model
-
id
string
The PayPal-generated ID for the resource. -
type
enum
required
The charge model type. -
The currency and amount for this charge model.
country_code
-
country_code
string
The two-character ISO 3166-1 code that identifies the country or region.Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
create_agreement_request
-
id
string
The PayPal-generated ID for the resource. -
state
enum
The state of the agreement. Value is:Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no more payments remain to be scheduled.
-
name
string
required
The agreement name. -
description
string
required
The agreement description. -
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
-
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
The ID of the plan on which this agreement is based.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
create_agreement_response
-
id
string
The PayPal-generated ID for the resource. -
state
enum
The state of the agreement. Value is:Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no more payments remain to be scheduled.
-
name
string
required
The agreement name. -
description
string
required
The agreement description. -
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a2017-01-02T14:36:21Z
start date and time for an account in the Berlin time zone (UTC + 1) to2017-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 internal2017-01-02T00:00:00
start date and time becomes2017-01-01T23:00:00
externally. -
agreement_details
The agreement details. -
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
-
shipping_address
The shipping address of the agreement, which must be provided if it differs from the default address. -
override_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 (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. -
The plan that can be used to create an agreement.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
credit_card
-
id
string
The PayPal-generated ID for the resource. -
number
string
required
The card number. -
type
string
required
The card type. For example, Visa, MasterCard, and so on. -
expire_month
integer
required
The two-digit card expiry month, inMM
format. Value is from01
to12
. -
expire_year
integer
required
The four-digit card expiry year, inYYYY
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. -
billing_address
The billing address associated with this card. -
external_customer_id
string
The facilitator-provided ID of the customer who owns this bank account. Required when storing a funding instrument or using a stored funding instrument in the PayPal vault. -
state
enum
The state of the funding instrument. -
valid_until
string
The date and time when the credit card becomes unusable from the vault, in Internet date and time format. Thevalid_until
parameter is not the same as the expiration month and year. The expiration month and year might be later than thevalid_until
date. For example, the card expires in November 2019 but thevalid_until
date is October 17th, 2019. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
currency
-
The three-character ISO-4217 currency code that identifies the currency.
-
value
string
required
The currency value. Might be an integer for currencies likeJPY
that are not typically fractional or a three-place decimal fraction for currencies likeTND
that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
currency_code
-
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
error
-
name
string
required
The human-readable, unique name of the error. -
debug_id
string
The PayPal internal ID. Used for correlation purposes. -
message
string
required
The message that describes the error. -
information_link
string
required
The URI to detailed information related to this error for the developer. -
details
array (contains the error_details object)
An array of additional details for the error.
error_details
-
field
string
required
The name of the field that caused the error. -
issue
string
required
The reason for the error.
funding_instrument
-
credit_card
A credit card that can be used to fund a payment.
link_description
-
href
string
required
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. Thehref
is the key HATEOAS component that links a completed call with a subsequent call. -
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations. -
method
enum
The HTTP method required to make the related call.
merchant_preferences
-
id
string
The PayPal-generated ID for the resource. -
setup_fee
The currency and amount of the fee to set up the agreement. Default is0
. -
cancel_url
string
required
The URL to which the customer is redirected if they cancel the agreement. -
return_url
string
required
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 is0
, which allows infinite failed payment attempts. -
auto_bill_amount
enum
Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is:NO
. PayPal does not automatically bill the customer the outstanding balance. Default isNO
.YES
. PayPal automatically bills the customer the outstanding balance.
-
initial_fail_amount_action
enum
The action if the customer's initial payment fails. Value is:CONTINUE
. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.CANCEL
. PayPal creates the agreement but sets its state to pending until the initial payment clears. When the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is cancelled.
-
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.
override_charge_model
-
charge_id
string
required
The ID of the charge model. -
The updated amount and currency for this charge model.
patch
-
op
enum
required
The operation to complete. -
path
string
The JSON pointer to the target document location at which to complete the operation. -
value
number,integer,string,boolean,null,array,object
The value to apply. Theremove
operation does not require a value. -
from
string
The JSON pointer to the target document location from which to move the value. Required for themove
operation.
patch_request
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
payer
-
payment_method
enum
required
The payment method. -
funding_instruments
array (contains the funding_instrument object)
An array of funding instruments. -
funding_option_id
string
The ID of the customer-selected funding option for the payment. Value isfunding_instruments
orfunding_option_id
. -
payer_info
The payer information.
payer_info
-
email
string
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
The shipping address for a payment. Must be provided if it differs from the default address. -
billing_address
The payer's billing address.
payment_definition
-
id
string
The PayPal-generated ID for the resource. -
name
string
required
The payment definition name. -
type
enum
required
The payment definition type. -
frequency_interval
string
required
The interval at which the customer is charged. Value cannot be greater than 12 months. -
frequency
enum
required
The frequency of the payment in this definition. -
cycles
string
required
The number of payment cycles in this definition. For infinite plans with a regular payment definition, setcycles
to0
. -
The currency and amount to charge at the end of each payment cycle for this definition.
-
charge_models
array (contains the charge_model object)
An array of shipping fee and tax information for this definition.
plan
-
id
string
The PayPal-generated ID for the resource. -
name
string
required
The plan name. -
description
string
required
The plan description. -
type
enum
required
The plan type. -
state
enum
The status of the plan. -
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 (contains the payment_definition object)
An array of payment definitions for this plan. -
terms
array (contains the terms object)
An array of terms for this plan. -
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. -
currency_code
The currency code for the plan. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
plan
-
id
string
The ID of the plan.
shipping_address
-
recipient_name
string
The name of the recipient at this address. -
default_address
boolean
The default shipping address of the payer.
-
line1
string
required
The first line of the address. For example, number or street. -
line2
string
The second line of the address. For example, suite or apartment number. -
city
string
required
The city name. -
state
string
-
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
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.
terms
-
id
string
The PayPal-generated ID for the resource. -
type
enum
required
The term type. -
The currency and amount of the maximum billing amount associated with this term.
-
occurrences
string
required
The number of times that money can be pulled during this term. -
The amount range for this term.
-
buyer_editable
string
required
Indicates whether the customer can edit the amount in this term.
Additional API information
Error messages
In addition to common HTTP status codes that the REST APIs return, the Billing Agreements API can return the following errors.