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.
Creates a billing agreement. In the JSON request body, include an agreement
object with the name, description, start date, ID of the plan on which to base the agreement, and customer and shipping address information.
name required | string <= 128 characters The agreement name. |
description required | string <= 128 characters The agreement description. |
start_date required | string <date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. |
object (Agreement Details) The agreement details. | |
required | object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. |
object (Merchant Preferences) The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails. | |
Array of objects (Override Charge Model) An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. | |
required | object (Plan) The ID of the plan on which this agreement is based. |
object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address. |
A successful request returns the HTTP 201 Created
status code and a JSON response body that shows billing agreement details including a billing agreement id
and redirect links to get the buyer's approval.
{- "name": "Direct Payment Recurring Profile",
- "description": "Credit card payment",
- "start_date": "2016-12-23T08:00:00Z",
- "payer": {
- "payment_method": "credit_card",
- "payer_info": {
- "email": "johndoe@example.com"
}, - "funding_instruments": [
- {
- "credit_card": {
- "type": "visa",
- "number": "4417119664863864",
- "expire_month": 12,
- "expire_year": 2021,
- "cvv2": 111,
- "billing_address": {
- "line1": "065769 Holcomb Bridge Road #141",
- "line2": "5713 E Dimond Boulevard #B9",
- "city": "Wichita",
- "state": "KS",
- "postal_code": "67202",
- "country_code": "US"
}
}
}
]
}, - "plan": {
- "id": "P-2PL786081D358645F6NWEKFQ"
}
}
{- "id": "I-Y6TL8T5KT95R",
- "state": "Active",
- "description": "Credit card payment.",
- "payer": {
- "payment_method": "credit_card",
- "payer_info": {
- "email": "johndoe@example.com"
}, - "funding_instruments": [
- {
- "credit_card": {
- "type": "visa",
- "number": "3864",
- "expire_month": 12,
- "expire_year": 2021,
- "start_month": "11",
- "start_year": "2016",
- "billing_address": {
- "line1": "065769 Holcomb Bridge Road #141",
- "line2": "5713 E Dimond Boulevard #B9",
- "city": "Wichita",
- "state": "KS",
- "postal_code": "67202",
- "country_code": "US"
}
}
}
]
}, - "plan": {
- "id": "P-2PL786081D358645F6NWEKFQ",
- "name": "Plan with Regular and Trial Payment Definitions",
- "description": "Plan with regular and trial payment definitions.",
- "type": "FIXED",
- "payment_definitions": [
- {
- "name": "Trial payment definition",
- "type": "TRIAL",
- "frequency": "MONTH",
- "amount": {
- "value": "0",
- "currency": "USD"
}, - "cycles": "2",
- "charge_models": [
- {
- "type": "TAX",
- "amount": {
- "value": "0",
- "currency": "USD"
}
}, - {
- "type": "SHIPPING",
- "amount": {
- "value": "0",
- "currency": "USD"
}
}
], - "frequency_interval": "1"
}, - {
- "name": "Regular payment definition",
- "type": "REGULAR",
- "frequency": "MONTH",
- "amount": {
- "value": "5.99",
- "currency": "USD"
}, - "cycles": "10",
- "charge_models": [
- {
- "type": "TAX",
- "amount": {
- "value": "0.29",
- "currency": "USD"
}
}, - {
- "type": "SHIPPING",
- "amount": {
- "value": "0.20",
- "currency": "USD"
}
}
], - "frequency_interval": "1"
}
], - "merchant_preferences": {
- "setup_fee": {
- "value": "0.40",
- "currency": "USD"
}, - "max_fail_attempts": "3",
- "auto_bill_amount": "YES"
}, - "links": [ ],
- "currency_code": "USD"
}, - "links": [
- {
- "rel": "self",
- "method": "GET"
}
], - "start_date": "2016-12-23T08:00:00Z",
- "agreement_details": {
- "outstanding_balance": {
- "value": "0.00",
- "currency": "USD"
}, - "cycles_remaining": "12",
- "cycles_completed": "0",
- "next_billing_date": "2017-01-23T08:00:00Z",
- "last_payment_date": "2016-12-23T08:00:00Z",
- "last_payment_amount": {
- "value": "0.40",
- "currency": "USD"
}, - "final_payment_date": "2017-09-23T08:00:00Z",
- "failed_payment_count": "0"
}
}
Executes a billing agreement, by ID, after customer approval.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows billing agreement details.
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/EC-7WN97463LN263864T/agreement-execute \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
{- "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"
}, - "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": [
- {
- "rel": "self",
- "method": "GET"
}
]
}
Shows details for a billing agreement, by ID.
A successful request returns the HTTP 200 OK
status code and a JSON response body that shows billing agreement details.
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-5D3XDN2D5FH1 \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
{- "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"
}, - "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": [
- {
- "rel": "suspend",
- "method": "POST"
}, - {
- "rel": "re_activate",
- "method": "POST"
}, - {
- "rel": "cancel",
- "method": "POST"
}, - {
- "rel": "self",
- "method": "POST"
}, - {
- "rel": "self",
- "method": "POST"
}
]
}
Updates details of a billing agreement, by ID. The details include the description, shipping address, start date, and so on.
Note: For the PayPal payment method, you cannot update the start_date
after the agreement is created.
op required | string The operation.
| ||||||||||||||||||||||||||
path | string The JSON Pointer to the target document location at which to complete the operation. | ||||||||||||||||||||||||||
value | object (Patch Value) The value to apply. The | ||||||||||||||||||||||||||
from | string The JSON Pointer to the target document location from which to move the value. Required for the |
A successful request returns the HTTP 200 OK
status code with no JSON response body.
[- {
- "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"
}
}
}
]
Suspends a billing agreement, by ID.
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
{- "note": "Suspending the profile."
}
Reactivates a suspended billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor
object with with a note that describes the reason for the reactivation and the agreement amount and currency.
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
{- "note": "Reactivating the profile."
}
Cancels a billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor
object with an optional note that describes the reason for the cancellation and the agreement amount and currency.
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
{- "note": "Canceling the profile."
}
Bills the balance for an agreement, by ID. In the JSON request body, include an optional note that describes the reason for the billing action and the agreement amount and currency.
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
{- "note": "Billing balance amount."
}
Sets the balance for an agreement, by ID. In the JSON request body, specify the balance currency type and value.
value required | string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ The currency value. Might be an integer for currencies like |
currency required | string <ppaas_common_currency_code_v2> (currency_code) = 3 characters The three-character ISO-4217 currency code that identifies the currency. |
A successful request returns the HTTP 204 No Content
status code with no JSON response body.
{- "value": "100",
- "currency": "USD"
}
Lists transactions for an agreement, by ID. To filter the transactions that appear in the response, specify the optional start and end date query parameters.
A successful request returns the HTTP 200 OK
status code and a JSON response body that lists transactions with details.
curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/transactions?start_date=2017-06-15&end_date=2017-06-17 \ -H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'
{- "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"
}
]
}
Message:
This transaction cannot be processed. Contact PayPal Customer Service.
Description: This account is restricted.
Message:
Invalid request - see details.
Description: Invalid agreement ID. The ID is the B-XXXXXXXXXXXXXXXXXX
type.
Message:
The billed amount should be less than the outstanding balance.
Description: The billed amount is too large.
Message:
This transaction cannot be processed.
Description: The country listed for your business address is not currently supported.
Message:
The profile description is not valid.
Description: Provide a valid agreement description.
Message:
The currency code is not valid. All currency codes much match.
Description: Use same currency code for all amount objects.
Message:
Cannot increase the delinquent amount.
Description: You cannot increase the outstanding amount for the bill.
Message:
Profile is not active.
Description: The state of the profile is not active.
Message:
The credit card type is not supported.
Description: Use another type of credit card.
Message:
DPRP is disabled for this merchant.
Description: To enable Direct Payment Recurring Payments (DPRP), enable Pro mode for your merchant sandbox account. Go to Sandbox accounts and click the Business account in the Type column. Click Profile and enable the Pro features on this business sandbox account.
Message:
The value of PayPal-Request-Id
header has already been used.
Description: Use a unique PayPal-Request-Id
header value to resend the request.
Message:
Business error.
Description: The buyer has not approved this token.
Message:
Business error.
Description: A session validation error occurred. The session does not belong to the merchant.
Message:
This transaction cannot be processed.
Description: This feature is disabled.
Message:
Because the recurring payments feature is not currently available, you must try again later.
Description: This feature is not available.
Message:
This transaction cannot be processed. Enter a valid credit card verification number.
Description: The verification number is not valid.
Message:
Internal Error.
Description: Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.
Message:
An internal service error has occurred.
Description: Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.
Message:
Invalid argument. The description field or custom field is empty and the status is active.
Description: Pass correct arguments in the description field and make sure that the status is active.
Message:
This transaction cannot be processed. Enter a valid credit card number and type.
Description: The credit card number and type are not valid.
Message:
This transaction cannot be processed due to an unsupported currency.
Description: This currency is not supported.
Message:
The profile status must be one of (A)ctive, (C)ancelled, or e(X)pired.
Description: Enter a valid profile status.
Message:
The status is not valid for the suspend action. The profile must be active.
Description: The agreement must be active before you can suspend it.
Message:
The activation type is not valid.
Description: Pass a valid activation type.
Message:
Invalid profile status for reactivate action. Profile must be suspended.
Description: To complete this action, you must first suspend the agreement.
Message:
Merchant account is denied.
Description: The merchant account is denied.
Message:
The merchant country is not supported.
Description: This country is not supported.
Message:
Business error.
Description: The merchant ID not authorized to get the details.
Message:
This transaction cannot be processed without a credit card verification number.
Description: Enter the credit card verification number.
Message:
Another outstanding payment is scheduled.
Description: Another payment is already scheduled.
Message:
The payer's account is denied.
Description: The payer's account is denied.
Message:
The payer's country is currently not supported.
Description: This country is not supported.
Message:
Invalid request - see details.
Description: Invalid payment method. Valid value is PAYPAL
.
Message:
Invalid request - see details.
Description: Invalid type mentioned. Valid values are MERCHANT_INITIATED_BILLING
or CHANNEL_INITIATED_BILLING
.
Message:
This credit card was issued from an unsupported country.
Description: This country is not supported.
Message:
The recurring payment was scheduled within 24 hours, so the bill outstanding amount cannot be processed.
Description: This bill outstanding amount cannot be processed.
Message:
Authorization error.
Description: This facilitator account is not permitted for Channel Initiated Billing.
Message:
Authorization error.
Description: This merchant account is not permitted to create Merchant Initiated Billing Agreement.
Message:
Access token does not have required scope.
Description: Obtain user consent by using the correct scope for this request type.
Message:
Business error.
Description: Failed Request: Agreement is already cancelled / Invalid agreement state.
Message:
Invalid currency for delinquent amount.
Description: Specify a valid currency in the bill-balance call.
Message:
This transaction cannot be processed. The shipping country is not allowed by the buyer's country of residence.
Description: The shipping country is not supported.
Message:
This transaction cannot be processed. Enter a valid country code in the shipping address.
Description: Enter a valid country code.
Message:
The subscription start date must be valid.
Description: Specify a valid start date in Internet date and time format. The start date must be greater than the current date.
Message:
The profile status is not valid for the reactivate action. The status must be active.
Description: Make sure that the status is active.
Message:
An internal error occurred.
Description: An internal error occurred.
Message:
The time of the update is too close to the billing date.
Description: You cannot make an update this close to the billing date.
Message:
Internal error.
Description: Invalid BA-Token Identifier. Valid token has the BA-XXXXXXXXXXXXXXXXX
format.
Message:
You do not have permission to create this agreement.
Description: You are not authorized to create this agreement.
Message:
This transaction cannot be processed due to an invalid merchant configuration.
Description: The merchant configuration is not valid.
Message:
Invalid request - see details.
Description: Your request has a validation error.
Message:
You have exceeded the maximum number of payment attempts for this token.
Description: Create a token and use it to create an agreement.
The billing agreement information.
id | string <= 128 characters The PayPal-generated ID for the resource. |
state | string <= 128 characters The state of the agreement. Value is:
|
description required | string <= 128 characters The agreement description. |
start_date required | string <date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. |
object (Agreement Details) The agreement details. | |
required | object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. |
object (Merchant Preferences) The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails. | |
Array of objects (Override Charge Model) An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. | |
required | object (Plan) The plan that can be used to create an agreement. |
Array of objects (Link Description) An array of request-related HATEOAS links. | |
object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address. |
{- "id": "string",
- "state": "Pending",
- "description": "string",
- "start_date": "2019-08-24T14:15:22Z",
- "agreement_details": {
- "cycles_remaining": "string",
- "cycles_completed": "string",
- "next_billing_date": "string",
- "last_payment_date": "string",
- "final_payment_date": "string",
- "failed_payment_count": "string",
- "outstanding_balance": {
- "value": "string",
- "currency": "string"
}, - "last_payment_amount": {
- "value": "string",
- "currency": "string"
}
}, - "payer": {
- "payment_method": "bank",
- "funding_instruments": [
- {
- "credit_card": {
- "id": "string",
- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": 0,
- "first_name": "string",
- "last_name": "string",
- "external_customer_id": "string",
- "state": "expired",
- "valid_until": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
}
], - "funding_option_id": "string",
- "payer_info": {
- "email": "user@example.com",
- "first_name": "string",
- "last_name": "string",
- "payer_id": "string",
- "shipping_address": {
- "recipient_name": "string",
- "default_address": true,
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}, - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
}, - "override_merchant_preferences": {
- "id": "string",
- "max_fail_attempts": "string",
- "auto_bill_amount": "YES",
- "initial_fail_amount_action": "CONTINUE",
- "accepted_payment_type": "string",
- "char_set": "string",
- "setup_fee": {
- "value": "string",
- "currency": "string"
}
}, - "override_charge_models": [
- {
- "charge_id": "string",
- "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "plan": {
- "id": "string",
- "name": "string",
- "description": "string",
- "type": "FIXED",
- "state": "CREATED",
- "create_time": "string",
- "update_time": "string",
- "payment_definitions": [
- {
- "id": "string",
- "name": "string",
- "type": "TRIAL",
- "frequency_interval": "string",
- "frequency": "WEEK",
- "cycles": "string",
- "charge_models": [
- {
- "id": "string",
- "type": "TAX",
- "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "terms": [
- {
- "id": "string",
- "type": "MONTHLY",
- "occurrences": "string",
- "buyer_editable": "string",
- "max_billing_amount": {
- "value": "string",
- "currency": "string"
}, - "amount_range": {
- "value": "string",
- "currency": "string"
}
}
], - "merchant_preferences": {
- "id": "string",
- "max_fail_attempts": "string",
- "auto_bill_amount": "YES",
- "initial_fail_amount_action": "CONTINUE",
- "accepted_payment_type": "string",
- "char_set": "string",
- "setup_fee": {
- "value": "string",
- "currency": "string"
}
}, - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "currency_code": "string"
}, - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "shipping_address": {
- "recipient_name": "string",
- "default_address": true,
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
The agreement details.
cycles_remaining | string The number of payment cycles remaining for this agreement. |
cycles_completed | string The number of payment cycles completed for this agreement. |
next_billing_date | string The next billing date and time for this agreement, in Internet date and time format. For example, |
last_payment_date | string The last payment date and time for this agreement, in Internet date and time format. For example, |
final_payment_date | string The final payment date and time for this agreement, in Internet date and time format. For example, |
failed_payment_count | string The total number of failed payments for this agreement. |
object (Currency) The currency and amount of the outstanding balance for this agreement. | |
object (Currency) The currency and amount of the last payment amount for this agreement. |
{- "cycles_remaining": "string",
- "cycles_completed": "string",
- "next_billing_date": "string",
- "last_payment_date": "string",
- "final_payment_date": "string",
- "failed_payment_count": "string",
- "outstanding_balance": {
- "value": "string",
- "currency": "string"
}, - "last_payment_amount": {
- "value": "string",
- "currency": "string"
}
}
The description of the current state of an agreement.
note | string <= 128 characters The reason for the agreement state change. |
{- "note": "string"
}
The agreement transaction.
transaction_id | string The ID of the transaction. |
status | string The current status of the transaction. Value is:
|
transaction_type | string The type of transaction. Typically, |
payer_email | string The email ID of the customer. |
payer_name | string The business name of the customer. |
time_stamp | string The date and time when the transaction occurred, in Internet date and time format. |
time_zone | string The time zone of the |
required | object (Currency) The currency and amount for a transaction. |
required | object (Currency) The currency and amount for a transaction. |
required | object (Currency) The currency and amount for a transaction. |
{- "transaction_id": "string",
- "status": "Completed",
- "transaction_type": "string",
- "payer_email": "string",
- "payer_name": "string",
- "time_stamp": "string",
- "time_zone": "string",
- "amount": {
- "value": "string",
- "currency": "string"
}, - "fee_amount": {
- "value": "string",
- "currency": "string"
}, - "net_amount": {
- "value": "string",
- "currency": "string"
}
}
An array of agreement transactions.
Array of objects (Agreement Transaction) An array of agreement transactions. |
{- "agreement_transaction_list": [
- {
- "transaction_id": "string",
- "status": "Completed",
- "transaction_type": "string",
- "payer_email": "string",
- "payer_name": "string",
- "time_stamp": "string",
- "time_zone": "string",
- "amount": {
- "value": "string",
- "currency": "string"
}, - "fee_amount": {
- "value": "string",
- "currency": "string"
}, - "net_amount": {
- "value": "string",
- "currency": "string"
}
}
]
}
The charge model for a payment definition. A charge model defines shipping fee and tax information.
id | string <= 128 characters The PayPal-generated ID for the resource. |
type required | string <= 20 characters The charge model type. |
required | object (Currency) The currency and amount for a transaction. |
{- "id": "string",
- "type": "TAX",
- "amount": {
- "value": "string",
- "currency": "string"
}
}
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
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.
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
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.
"st"
The billing agreement information.
id | string <= 128 characters The PayPal-generated ID for the resource. |
state | string <= 128 characters The state of the agreement. Value is:
|
name required | string <= 128 characters The agreement name. |
description required | string <= 128 characters The agreement description. |
start_date required | string <date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. |
object (Agreement Details) The agreement details. | |
required | object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. |
object (Merchant Preferences) The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails. | |
Array of objects (Override Charge Model) An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. | |
required | object (Plan) The ID of the plan on which this agreement is based. |
Array of objects (Link Description) An array of request-related HATEOAS links. | |
object (Shipping Address) The shipping address for a payment. Must be provided if it differs from the default address. |
{- "id": "string",
- "state": "Pending",
- "name": "string",
- "description": "string",
- "start_date": "2019-08-24T14:15:22Z",
- "agreement_details": {
- "cycles_remaining": "string",
- "cycles_completed": "string",
- "next_billing_date": "string",
- "last_payment_date": "string",
- "final_payment_date": "string",
- "failed_payment_count": "string",
- "outstanding_balance": {
- "value": "string",
- "currency": "string"
}, - "last_payment_amount": {
- "value": "string",
- "currency": "string"
}
}, - "payer": {
- "payment_method": "bank",
- "funding_instruments": [
- {
- "credit_card": {
- "id": "string",
- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": 0,
- "first_name": "string",
- "last_name": "string",
- "external_customer_id": "string",
- "state": "expired",
- "valid_until": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
}
], - "funding_option_id": "string",
- "payer_info": {
- "email": "user@example.com",
- "first_name": "string",
- "last_name": "string",
- "payer_id": "string",
- "shipping_address": {
- "recipient_name": "string",
- "default_address": true,
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}, - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
}, - "override_merchant_preferences": {
- "id": "string",
- "max_fail_attempts": "string",
- "auto_bill_amount": "YES",
- "initial_fail_amount_action": "CONTINUE",
- "accepted_payment_type": "string",
- "char_set": "string",
- "setup_fee": {
- "value": "string",
- "currency": "string"
}
}, - "override_charge_models": [
- {
- "charge_id": "string",
- "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "plan": {
- "id": "string"
}, - "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "shipping_address": {
- "recipient_name": "string",
- "default_address": true,
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
The billing agreement information.
id | string <= 128 characters The PayPal-generated ID for the resource. |
state | string <= 128 characters The state of the agreement. Value is:
|
name required | string <= 128 characters The agreement name. |
description required | string <= 128 characters The agreement description. |
start_date required | string <date-time> The date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate. |
object (Agreement Details) The agreement details. | |
required | object (Payer) The details for the customer who funds the payment. The API gathers this information from execution of the approval URL. |
object (Merchant Preferences) The merchant preferences that override the default information in the plan. If you omit this parameter, the agreement uses the default merchant preferences from the plan. The merchant preferences include how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails. | |
Array of objects (Override Charge Model) An array of charge models to override the charge models in the plan. A charge model defines shipping fee and tax information. If you omit this parameter, the agreement uses the default shipping fee and tax information from the plan. | |
required | object (Plan) The plan that can be used to create an agreement. |
Array of objects (Link Description) An array of request-related HATEOAS links. | |
object (Simple Postal Address (Coarse-Grained)) The shipping address of the agreement, which must be provided if it differs from the default address. |
{- "id": "string",
- "state": "Pending",
- "name": "string",
- "description": "string",
- "start_date": "2019-08-24T14:15:22Z",
- "agreement_details": {
- "cycles_remaining": "string",
- "cycles_completed": "string",
- "next_billing_date": "string",
- "last_payment_date": "string",
- "final_payment_date": "string",
- "failed_payment_count": "string",
- "outstanding_balance": {
- "value": "string",
- "currency": "string"
}, - "last_payment_amount": {
- "value": "string",
- "currency": "string"
}
}, - "payer": {
- "payment_method": "bank",
- "funding_instruments": [
- {
- "credit_card": {
- "id": "string",
- "number": "string",
- "type": "string",
- "expire_month": 0,
- "expire_year": 0,
- "cvv2": 0,
- "first_name": "string",
- "last_name": "string",
- "external_customer_id": "string",
- "state": "expired",
- "valid_until": "string",
- "links": [
- {
- "href": "string",
- "rel": "string",
- "method": "GET"
}
], - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
}
], - "funding_option_id": "string",
- "payer_info": {
- "email": "user@example.com",
- "first_name": "string",
- "last_name": "string",
- "payer_id": "string",
- "shipping_address": {
- "recipient_name": "string",
- "default_address": true,
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}, - "billing_address": {
- "line1": "string",
- "line2": "string",
- "city": "string",
- "state": "string",
- "country_code": "st",
- "postal_code": "string"
}
}
}, - "override_merchant_preferences": {
- "id": "string",
- "max_fail_attempts": "string",
- "auto_bill_amount": "YES",
- "initial_fail_amount_action": "CONTINUE",
- "accepted_payment_type": "string",
- "char_set": "string",
- "setup_fee": {
- "value": "string",
- "currency": "string"
}
}, - "override_charge_models": [
- {
- "charge_id": "string",
- "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "plan": {
- "id": "string",
- "name": "string",
- "description": "string",
- "type": "FIXED",
- "state": "CREATED",
- "create_time": "string",
- "update_time": "string",
- "payment_definitions": [
- {
- "id": "string",
- "name": "string",
- "type": "TRIAL",
- "frequency_interval": "string",
- "frequency": "WEEK",
- "cycles": "string",
- "charge_models": [
- {
- "id": "string",
- "type": "TAX",
- "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "amount": {
- "value": "string",
- "currency": "string"
}
}
], - "terms": [
- {
- "id": "string",
- "type": "MONTHLY",
- "occurrences": "string",
- "buyer_editable": "string",
- "max_billing_amount": {
- "value": "string",
- "currency": "string"
}, - "amount_range": {
- "value": "string",
- "currency": "string"
}
}
], - "merchant_preferences": {
- "id": "string",
- "max_fail_attempts": "string"