Billing Agreements API
Deprecation notice: TheUse 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./v1/payments/billing-agreements
endpoints are deprecated. Use the/v1/billing/subscriptions
endpoints instead. For details, see Subscriptions Integration.
Important: The use of the PayPal REST /payments
APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.
Note: The Billing Agreements API does not support the payee
object.
Billing agreements (resource group)
Use the /billing-agreements
resource to create, update, show details for, bill the balance for, cancel, reactivate, set the balance for, suspend, list transactions for, and execute agreements.
Create agreement
agreement
object with the name, description, start date, ID of the plan on which to base the agreement, and customer and shipping address information.Request body
description
string
required
The agreement description.
name
string
required
The agreement name.
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
The ID of the plan on which this agreement is based.
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address.
state
enum
The state of the agreement. Value is:
Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no more payments remain to be scheduled.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"name": "Override Agreement",
"description": "PayPal payment agreement that overrides merchant preferences and shipping fee and tax information.",
"start_date": "2017-12-22T09:13:49Z",
"payer": {
"payment_method": "paypal",
"payer_info": {
"email": "payer@example.com"
}
},
"plan": {
"id": "P-1WJ68935LL406420PUTENA2I"
},
"shipping_address": {
"line1": "Hotel Staybridge",
"line2": "Crooke Street",
"city": "San Jose",
"state": "CA",
"postal_code": "95112",
"country_code": "US"
},
"override_merchant_preferences": {
"setup_fee": {
"value": "3",
"currency": "GBP"
},
"return_url": "https://example.com/",
"cancel_url": "https://example.com/cancel",
"auto_bill_amount": "YES",
"initial_fail_amount_action": "CONTINUE",
"max_fail_attempts": "11"
},
"override_charge_models": [
{
"charge_id": "CHM-8373958130821962WUTENA2Q",
"amount": {
"value": "1",
"currency": "GBP"
}
}
]
}'
Response
201 Created
status code and a JSON response body that shows billing agreement details including a billing agreement id
and redirect links to get the buyer's approval.agreement_details
The agreement details.
description
string
The agreement description.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
name
string
The agreement name.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
payer
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
plan
The plan that can be used to create an agreement.
shipping_address
The shipping address of the agreement, which must be provided if it differs from the default address.
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.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.
Sample Response
{
"name": "Override Agreement",
"description": "Agreement that overrides merchant preferences and charge models",
"payer": {
"payment_method": "paypal",
"payer_info": {
"email": "payer@example.com"
}
},
"plan": {
"id": "P-1WJ68935LL406420PUTENA2I",
"state": "ACTIVE",
"name": "Fast Speed Plan",
"description": "Vanilla plan",
"type": "INFINITE",
"payment_definitions": [
{
"id": "PD-9WG6983719571780GUTENA2I",
"name": "Regular payment definition",
"type": "REGULAR",
"frequency": "DAY",
"amount": {
"currency": "GBP",
"value": "10"
},
"charge_models": [
{
"id": "CHM-8373958130821962WUTENA2Q",
"type": "SHIPPING",
"amount": {
"currency": "GBP",
"value": "1"
}
},
{
"id": "CHM-2937144979861454NUTENA2Q",
"type": "TAX",
"amount": {
"currency": "GBP",
"value": "2"
}
}
],
"cycles": "0",
"frequency_interval": "1"
},
{
"id": "PD-89M493313S710490TUTENA2Q",
"name": "Trial payment definition",
"type": "TRIAL",
"frequency": "MONTH",
"amount": {
"currency": "GBP",
"value": "100"
},
"charge_models": [
{
"id": "CHM-78K47820SS4923826UTENA2Q",
"type": "SHIPPING",
"amount": {
"currency": "GBP",
"value": "10"
}
},
{
"id": "CHM-9M366179U7339472RUTENA2Q",
"type": "TAX",
"amount": {
"currency": "GBP",
"value": "12"
}
}
],
"cycles": "5",
"frequency_interval": "2"
}
],
"merchant_preferences": {
"setup_fee": {
"currency": "GBP",
"value": "3"
},
"max_fail_attempts": "11",
"return_url": "https://example.com/",
"cancel_url": "https://example.com/cancel",
"auto_bill_amount": "YES",
"initial_fail_amount_action": "CONTINUE"
}
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-83C745436S346813F",
"rel": "approval_url",
"method": "REDIRECT"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/EC-83C745436S346813F/agreement-execute",
"rel": "execute",
"method": "POST"
}
],
"start_date": "2017-12-22T09:13:49Z"
}
Update agreement
Note: For the PayPal payment method, you cannot update the start_date
after the agreement is created.
Path parameters
agreement_id
string
required
The ID of the agreement to update.
Request body
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
Sample Request
curl -v -X PATCH https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "replace",
"path": "/",
"value": {
"description": "Updated description.",
"start_date": "2017-12-22T09:13:49Z",
"shipping_address": {
"line1": "Hotel Blue Diamond",
"line2": "Church Street",
"city": "San Jose",
"state": "CA",
"postal_code": "95112",
"country_code": "US"
}
}
}
]'
Response
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.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-5D3XDN2D5FH1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows billing agreement details.agreement_details
The agreement details.
description
string
The agreement description.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
payer
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
plan
The plan that can be used to create an agreement.
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address.
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.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.
Sample Response
{
"id": "I-1TJ3GAGG82Y9",
"state": "Active",
"description": "Monthly agreement with free trial payment definition.",
"payer": {
"payment_method": "paypal",
"status": "unverified",
"payer_info": {
"email": "johndoe@example.com",
"first_name": "John",
"last_name": "Doe",
"payer_id": "NEW8A85AK4ET4",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
}
}
},
"plan": {
"name": "Plan with Regular and Trial Payment Definitions",
"description": "Plan with regular and trial payment definitions.",
"type": "FIXED",
"payment_definitions": [
{
"name": "Trial payment definition",
"type": "TRIAL",
"frequency": "MONTH",
"amount": {
"value": "0.00",
"currency": "USD"
},
"cycles": "2",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.00",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.00",
"currency": "USD"
}
}
],
"frequency_interval": "1"
},
{
"name": "Regular payment definition",
"type": "REGULAR",
"frequency": "MONTH",
"amount": {
"value": "5.99",
"currency": "USD"
},
"cycles": "10",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.29",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.20",
"currency": "USD"
}
}
],
"frequency_interval": "1"
}
],
"merchant_preferences": {
"setup_fee": {
"value": "0.40",
"currency": "USD"
},
"return_url": "https://example.com",
"cancel_url": "https://example.com/cancel",
"max_fail_attempts": "2",
"auto_bill_amount": "YES"
},
"links": [],
"currency_code": "USD"
},
"start_date": "2016-12-23T08:00:00Z",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
},
"agreement_details": {
"outstanding_balance": {
"currency": "USD",
"value": "0.00"
},
"cycles_remaining": "2",
"cycles_completed": "0",
"next_billing_date": "2017-01-23T08:00:00Z",
"last_payment_date": "2016-12-23T08:00:00Z",
"last_payment_amount": {
"currency": "USD",
"value": "0.40"
},
"final_payment_date": "2017-09-23T08:00:00Z",
"failed_payment_count": "0"
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend",
"rel": "suspend",
"method": "POST"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate",
"rel": "re_activate",
"method": "POST"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance",
"rel": "self",
"method": "POST"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance",
"rel": "self",
"method": "POST"
}
]
}
Bill agreement balance
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.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/bill-balance \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"note": "Billing balance amount."
}'
Response
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.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"note": "Canceling the profile."
}'
Response
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.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/re-activate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"note": "Reactivating the profile."
}'
Response
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 like
JPY
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.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/set-balance \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"value": "100",
"currency": "USD"
}'
Response
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.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/suspend \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"note": "Suspending the profile."
}'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
List agreement transactions
Query parameters
end_date
string
The end date of the range of transactions to list.
start_date
string
The start date of the range of transactions to list.
Path parameters
agreement_id
string
required
The ID of the agreement for which to list transactions.
Sample Request
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/transactions?start_date=2017-06-15&end_date=2017-06-17 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
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.
Sample Request
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows billing agreement details.agreement_details
The agreement details.
description
string
The agreement description.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
payer
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
plan
The plan that can be used to create an agreement.
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address.
start_date
string
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.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.
Sample Response
{
"id": "I-1TJ3GAGG82Y9",
"state": "Active",
"description": "Monthly agreement with free trial payment definition.",
"payer": {
"payment_method": "paypal",
"status": "unverified",
"payer_info": {
"email": "johndoe@example.com",
"first_name": "John",
"last_name": "Doe",
"payer_id": "NEW8A85AK4ET4",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
}
}
},
"plan": {
"name": "Plan with Regular and Trial Payment Definitions",
"description": "Plan with regular and trial payment definitions.",
"type": "FIXED",
"payment_definitions": [
{
"name": "Trial payment definition",
"type": "TRIAL",
"frequency": "MONTH",
"amount": {
"value": "0.00",
"currency": "USD"
},
"cycles": "2",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.00",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.00",
"currency": "USD"
}
}
],
"frequency_interval": "1"
},
{
"name": "Regular payment definition",
"type": "REGULAR",
"frequency": "MONTH",
"amount": {
"value": "5.99",
"currency": "USD"
},
"cycles": "10",
"charge_models": [
{
"type": "TAX",
"amount": {
"value": "0.29",
"currency": "USD"
}
},
{
"type": "SHIPPING",
"amount": {
"value": "0.20",
"currency": "USD"
}
}
],
"frequency_interval": "1"
}
],
"merchant_preferences": {
"setup_fee": {
"value": "0.40",
"currency": "USD"
},
"return_url": "https://example.com",
"cancel_url": "https://example.com/cancel",
"max_fail_attempts": "2",
"auto_bill_amount": "YES"
},
"links": [],
"currency_code": "USD"
},
"start_date": "2016-12-23T08:00:00Z",
"shipping_address": {
"recipient_name": "John Doe",
"line1": "751235 Stout Drive",
"line2": "0976249 Elizabeth Court",
"city": "Quimby",
"state": "IA",
"postal_code": "51049",
"country_code": "US"
},
"agreement_details": {
"outstanding_balance": {
"value": "0.00",
"currency": "USD"
},
"cycles_remaining": "2",
"cycles_completed": "0",
"next_billing_date": "2017-01-23T08:00:00Z",
"last_payment_date": "2016-12-23T08:00:00Z",
"last_payment_amount": {
"value": "0.40",
"currency": "USD"
},
"final_payment_date": "2017-09-23T08:00:00Z",
"failed_payment_count": "0"
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
address
city
string
required
The city name.
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.line1
string
required
The first line of the address. For example, number or street.
line2
string
The second line of the address. For example, suite or apartment number.
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
state
string
address_postal_code_validation
address_postal_code_validation
agreement
description
string
required
The agreement description.
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
The plan that can be used to create an agreement.
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address.
state
enum
The state of the agreement. Value is:
Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no payments remain to be scheduled.
agreement_details
cycles_completed
string
The number of payment cycles completed for this agreement.
cycles_remaining
string
The number of payment cycles remaining for this agreement.
failed_payment_count
string
The total number of failed payments for this agreement.
final_payment_date
string
The final payment date and time for this agreement, in Internet date and time format. For example,
2017-09-23T08:00:00Z
.last_payment_amount
The currency and amount of the last payment amount for this agreement.
last_payment_date
string
The last payment date and time for this agreement, in Internet date and time format. For example,
2016-12-23T08:00:00Z
.next_billing_date
string
The next billing date and time for this agreement, in Internet date and time format. For example,
2017-01-23T08:00:00Z
.outstanding_balance
The currency and amount of the outstanding balance for this agreement.
agreement_state_descriptor
note
string
The reason for the agreement state change.
agreement_transaction
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.
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.
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.transaction_id
string
The ID of the transaction.
transaction_type
string
The type of transaction. Typically,
Recurring Payment
.
agreement_transactions
agreement_transaction_list
array (contains the agreement_transaction object)
An array of agreement transactions.
bank_account
account_number
string
required
The account number in international bank account number (IBAN) format or basic bank account number (BBAN) format. The maximum length for the IBAN format is 34 characters. The maximum length for the BBAN format is 17 characters.
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.
account_name
string
A customer-designated account name.
account_type
enum
The bank account type.
auth_capture_timestamp
string
The date and time when the authorization was captured, in Internet date and time format. Use this parameter if you must capture the user authorization due to any privacy requirements.
auth_type
enum
The authorization type, which indicates how the check was obtained from the customer if a check is the source of information.
bank_name
string
The bank name.
billing_address
The billing address.
birth_date
string
The account holder's birth date.
check_type
enum
The check type when the information was obtained from the facilitator or merchant.
confirmation_status
enum
The confirmation status of a bank account.
country_code
string
The two-letter country code of the bank.
create_time
string
The date and time when the bank account was created, in Internet date and time format.
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.
first_name
string
The account holder's first name.
id
string
The PayPal-generated ID for the resource.
last_name
string
The account holder's last name.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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.
payer_id
string
Deprecated. Instead, use the
external_customer_id
parameter.routing_number
string
The routing transit number, or bank code, of the bank. Typically, you specify this value for domestic use only. International bank account numbers (IBAN) include the bank code. For more information, see Bank code.
state
enum
The state of this funding instrument.
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.
charge_model
The currency and amount for this charge model.
type
enum
required
The charge model type.
id
string
The PayPal-generated ID for the resource.
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
description
string
required
The agreement description.
name
string
required
The agreement name.
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
The ID of the plan on which this agreement is based.
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
shipping_address
The shipping address for a payment. Must be provided if it differs from the default address.
state
enum
The state of the agreement. Value is:
Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no more payments remain to be scheduled.
create_agreement_response
description
string
required
The agreement description.
name
string
required
The agreement name.
The details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
The plan that can be used to create an agreement.
start_date
string
required
The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts 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.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
override_charge_models
array (contains the override_charge_model object)
An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan.
override_merchant_preferences
The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.
shipping_address
The shipping address of the agreement, which must be provided if it differs from the default address.
state
enum
The state of the agreement. Value is:
Pending
. The agreement awaits initial payment completion.Active
. The agreement is active and payments are scheduled.Suspended
. The agreement is suspended and payments are not scheduled until the agreement is reactivated.Cancelled
. The agreement is cancelled and payments are not scheduled.Expired
. The agreement is expired and no more payments remain to be scheduled.
credit_card
expire_month
integer
required
The two-digit card expiry month, in
MM
format. Value is from01
to12
.expire_year
integer
required
The four-digit card expiry year, in
YYYY
format.number
string
required
The card number.
type
string
required
The card type. For example, Visa, MasterCard, and so on.
billing_address
The billing address associated with this card.
cvv2
integer
The card validation code. Supported only when making a payment but not when saving a credit card for future use.
external_customer_id
string
The facilitator-provided ID of the customer who owns this bank account. Required when storing a funding instrument or using a stored funding instrument in the PayPal vault.
first_name
string
The first name of the card holder.
id
string
The PayPal-generated ID for the resource.
last_name
string
The last name of the card holder.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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. The
valid_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.
currency
The three-character ISO-4217 currency code that identifies the currency.
value
string
required
The currency value. Might be an integer for currencies like
JPY
that are not typically fractional or a three-place decimal fraction for currencies 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
information_link
string
required
The URI to detailed information related to this error for the developer.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
debug_id
string
The PayPal internal ID. Used for correlation purposes.
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
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.
accepted_payment_type
string
The payment types that are accepted for this agreement. Read-only and reserved for future use.
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.
char_set
string
The character set for this agreement. Read-only and reserved for future use.
id
string
The PayPal-generated ID for the resource.
initial_fail_amount_action
enum
The action if the customer's initial payment fails. Value is:
CONTINUE
. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.CANCEL
. PayPal creates the agreement but sets its state to pending until the initial payment clears. When the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is cancelled.
Note: Initial payment failures will not increment the
max_fail_attempt
counter as initial payments are not considered regularly recurring payments.max_fail_attempts
string
The maximum number of allowed failed payment attempts. Default is
0
, which allows infinite failed payment attempts.setup_fee
The currency and amount of the fee to set up the agreement. Default is
0
.
override_charge_model
The updated amount and currency for this charge model.
charge_id
string
required
The ID of the charge model.
patch
op
enum
required
The operation.
The possible values are:
add
. Depending on the target location reference, completes one of these functions:- The target location is an array index. Inserts a new value into the array at the specified index.
- The target location is an object parameter that does not already exist. Adds a new parameter to the object.
- The target location is an object parameter that does exist. Replaces that parameter's value.
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 avalue
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 afrom
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, thefrom
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 afrom
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, thefrom
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 avalue
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 thevalue
value. For test,equal
indicates that the value at the target location and the value thatvalue
defines are of the same JSON type. The data type of the value determines how equality is defined:
For more information, see 4.6. test.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
, andnull
)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.
from
string
The JSON Pointer to the target document location from which to move the value. Required for the
move
operation.path
string
The JSON Pointer to the target document location at which to complete the operation.
value
number,integer,string,boolean,null,array,object
The value to apply. The
remove
operation does not require a value.
patch_request
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
payer
payment_method
enum
required
The payment method.
funding_instruments
array (contains the funding_instrument object)
An array of funding instruments.
funding_option_id
string
The ID of the customer-selected funding option for the payment. Value is
funding_instruments
orfunding_option_id
.payer_info
The payer information.
payer_info
billing_address
The payer's billing address.
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.
payment_definition
The currency and amount to charge at the end of each payment cycle for this definition.
cycles
string
required
The number of payment cycles in this definition. For infinite plans with a regular payment definition, set
cycles
to0
.frequency
enum
required
The frequency of the payment in this definition.
Note: You can specify the
frequency
value in any case. For example, you can specify the frequency of the payment asWEEK
,Week
, orweek
.The possible values are:
WEEK
. The payment is weekly.DAY
. The payment is daily.YEAR
. The payment is yearly.MONTH
. The payment is monthly.
frequency_interval
string
required
The interval at which the customer is charged. Value cannot be greater than 12 months.
name
string
required
The payment definition name.
type
enum
required
The payment definition type.
charge_models
array (contains the charge_model object)
An array of shipping fee and tax information for this definition.
id
string
The PayPal-generated ID for the resource.
plan
description
string
required
The plan description.
name
string
required
The plan name.
type
enum
required
The plan type.
create_time
string
The date and time when the plan was created, in Internet date and time format.
currency_code
The currency code for the plan.
id
string
The PayPal-generated ID for the resource.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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.
payment_definitions
array (contains the payment_definition object)
An array of payment definitions for this plan.
state
enum
The status of the plan.
terms
array (contains the terms object)
An array of terms for this plan.
update_time
string
The date and time when this plan was updated, in Internet date and time format.
plan
id
string
The ID of the plan.
shipping_address
default_address
boolean
The default shipping address of the payer.
recipient_name
string
The name of the recipient at this address.
city
string
required
The city name.
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.line1
string
required
The first line of the address. For example, number or street.
line2
string
The second line of the address. For example, suite or apartment number.
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
state
string
terms
The amount range for this term.
buyer_editable
string
required
Indicates whether the customer can edit the amount in this term.
The currency and amount of the maximum billing amount associated with this term.
occurrences
string
required
The number of times that money can be pulled during this term.
type
enum
required
The term type.
The possible values are:
MONTHLY
. The term is monthly.WEEKLY
. The term is weekly.YEARLY
. The term is yearly.
id
string
The PayPal-generated ID for the resource.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Billing Agreements API can return the following errors.