On this page
No Headings
The billing agreement information.
objectidstringThe PayPal-generated ID for the resource.
statestring"Pending", "Active", "Suspended", "Cancelled", "Expired"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.namerequiredstringThe agreement name.
descriptionrequiredstringThe agreement description.
start_daterequiredstringdate-timeThe date and time when this agreement begins, in Internet date and time format. The start date must be no less than 24 hours after the current date as the agreement can take up to 24 hours to activate.
The start date and time in the create agreement request might not match the start date and time that the API returns in the execute agreement response. When you execute an agreement, the API internally converts the start date and time to the start of the day in the time zone of the merchant account. For example, the API converts a 2017-01-02T14:36:21Z start date and time for an account in the Berlin time zone (UTC + 1) to 2017-01-02T00:00:00. When the API returns this date and time in the execute agreement response, it shows the converted date and time in the UTC time zone. So, the internal 2017-01-02T00:00:00 start date and time becomes 2017-01-01T23:00:00 externally.
agreement_detailsobjectThe agreement details.
cycles_remainingstringThe number of payment cycles remaining for this agreement.
cycles_completedstringThe number of payment cycles completed for this agreement.
next_billing_datestringThe next billing date and time for this agreement, in Internet date and time format. For example, 2017-01-23T08:00:00Z.
last_payment_datestringThe last payment date and time for this agreement, in Internet date and time format. For example, 2016-12-23T08:00:00Z.
final_payment_datestringThe final payment date and time for this agreement, in Internet date and time format. For example, 2017-09-23T08:00:00Z.
failed_payment_countstringThe total number of failed payments for this agreement.
outstanding_balanceobjectThe currency and amount of the outstanding balance for this agreement.
The currency and amount for a transaction.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
currencyrequiredobjectppaas_common_currency_code_v2The three-character ISO-4217 currency code that identifies the currency.
last_payment_amountobjectThe currency and amount of the last payment amount for this agreement.
The currency and amount for a transaction.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
currencyrequiredobjectppaas_common_currency_code_v2The three-character ISO-4217 currency code that identifies the currency.
payerrequiredobjectThe details for the customer who funds the payment. The API gathers this information from execution of the approval URL.
payment_methodrequiredstring"bank", "paypal"The payment method.
funding_instrumentsarrayAn array of funding instruments.
itemsobjectThe customer's funding instrument that can be used to fund a payment.
credit_cardobjectThe credit card that can be used to fund a payment.
A credit card that can be used to fund a payment.
idstringThe PayPal-generated ID for the resource.
numberrequiredstringThe card number.
typerequiredstringThe card type. For example, Visa, MasterCard, and so on.
expire_monthrequiredintegerThe two-digit card expiry month, in MM format. Value is from 01 to 12.
expire_yearrequiredintegerThe four-digit card expiry year, in YYYY format.
cvv2integerThe card validation code. Supported only when making a payment but not when saving a credit card for future use.
first_namestringThe first name of the card holder.
last_namestringThe last name of the card holder.
external_customer_idstringThe 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.
statestring"expired", "ok"The state of the funding instrument.
valid_untilstringThe date and time when the credit card becomes unusable from the vault, in Internet date and time format. The valid_until parameter is not the same as the expiration month and year. The expiration month and year might be later than the valid_until date. For example, the card expires in November 2019 but the valid_until date is October 17th, 2019.
linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstringThe complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
relrequiredstringThe link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"The HTTP method required to make the related call.
billing_addressobjectA simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.
The billing address associated with this card.
line1requiredstringThe first line of the address. For example, number or street.
line2stringThe second line of the address. For example, suite or apartment number.
cityrequiredstringThe city name.
statestringcountry_coderequiredstringppaas_common_country_code_v2^([A-Z]{2}|C2)$The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_codestringThe postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
funding_option_idstringThe ID of the customer-selected funding option for the payment. Value is funding_instruments or funding_option_id.
payer_infoobjectThe payer information.
emailstringemailThe payer's email address.
first_namestringThe payer's first name.
last_namestringThe payer's last name.
payer_idstringThe PayPal-assigned ID for the payer.
shipping_addressobjectThe shipping address for a payment. Must be provided if it differs from the default address.
billing_addressobjectA simple postal address with coarse-grained fields. Do not use for an international address. Use for backward compatibility only. Does not contain phone.
The payer's billing address.
line1requiredstringThe first line of the address. For example, number or street.
line2stringThe second line of the address. For example, suite or apartment number.
cityrequiredstringThe city name.
statestringcountry_coderequiredstringppaas_common_country_code_v2^([A-Z]{2}|C2)$The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas used in the top-level domain names for that country. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_codestringThe postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
override_merchant_preferencesobjectThe 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.
idstringThe PayPal-generated ID for the resource.
cancel_urlrequiredstringuriThe URL to which the customer is redirected if they cancel the agreement.
return_urlrequiredstringuriThe URL to which the customer is redirected if they accept the agreement.
max_fail_attemptsstringThe maximum number of allowed failed payment attempts. Default is 0, which allows infinite failed payment attempts.
auto_bill_amountstring"YES", "NO"Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is:
NO. PayPal does not automatically bill the customer the outstanding balance. Default is NO.YES. PayPal automatically bills the customer the outstanding balance.initial_fail_amount_actionstring"CONTINUE", "CANCEL""CONTINUE"The action if the customer's initial payment fails. Value is:
CONTINUE. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.CANCEL. PayPal creates the agreement but sets its state to pending until the initial payment clears. When the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is cancelled.Note: Initial payment failures will not increment the max_fail_attempt counter as initial payments are not considered regularly recurring payments.accepted_payment_typestringThe payment types that are accepted for this agreement. Read-only and reserved for future use.
char_setstringThe character set for this agreement. Read-only and reserved for future use.
setup_feeobjectThe currency and amount for a transaction.
The currency and amount of the fee to set up the agreement. Default is 0.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
currencyrequiredobjectppaas_common_currency_code_v2The three-character ISO-4217 currency code that identifies the currency.
override_charge_modelsarrayAn 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.
itemsobjectThe charge model that overrides default charge information during agreement creation.
charge_idrequiredstringThe ID of the charge model.
amountrequiredobjectThe currency and amount for a transaction.
The updated amount and currency for this charge model.
valuerequiredstring^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$The currency value. Might be an integer for currencies like JPY that are not typically fractional or a three-place decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
currencyrequiredobjectppaas_common_currency_code_v2The three-character ISO-4217 currency code that identifies the currency.
planrequiredobjectThe ID of the plan on which this agreement is based.
idstringThe ID of the plan.
linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstringThe complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
relrequiredstringThe link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"The HTTP method required to make the related call.
shipping_addressobjectThe shipping address for a payment. Must be provided if it differs from the default address.