CreateRecurringPaymentsProfile API Operation (NVP)

The CreateRecurringPaymentsProfile API operation creates a recurring payments profile. You must invoke the CreateRecurringPaymentsProfile API operation for each profile you want to create. The API operation creates a profile and an associated billing agreement.

Note There is a one-to-one correspondence between billing agreements and recurring payments profiles. To associate a recurring payments profile with its billing agreement, you must ensure that the description in the recurring payments profile matches the description of a billing agreement. For version 54.0 and later, use SetExpressCheckout to initiate creation of a billing agreement.

CreateRecurringPaymentsProfile Request Message

CreateRecurringPaymentsProfile Request Fields

Field Description

METHOD

(Required) Must be CreateRecurringPaymentsProfile.

TOKEN

A timestamped token, the value of which was returned in the response to the first call to SetExpressCheckout. You can also use the token returned in the SetCustomerBillingAgreement response. Either this token or a credit card number is required. If you include both token and credit card number, the token is used and credit card number is ignored Call CreateRecurringPaymentsProfile once for each billing agreement included in SetExpressCheckout request and use the same token for each call. Each CreateRecurringPaymentsProfile request creates a single recurring payments profile.

Note Tokens expire after approximately 3 hours.

Recurring Payments Profile Details Fields

Field Description

SUBSCRIBERNAME

(Optional) Full name of the person receiving the product or service paid for by the recurring payment. If not present, the name in the buyer's PayPal account is used.

Character length and limitations: 32 single-byte characters

PROFILESTARTDATE

(Required) The date when billing for this profile begins.

Note The profile may take up to 24 hours for activation.

Character length and limitations: Must be a valid date, in UTC/GMT format; for example, 2013-08-24T05:38:48Z. No wildcards are allowed.

PROFILEREFERENCE

(Optional) The merchant's own unique reference or invoice number.

Character length and limitations: 127 single-byte alphanumeric characters

Schedule Details Fields

Field Description

DESC

(Required) Description of the recurring payment.

Note You must ensure that this field matches the corresponding billing agreement description included in the SetExpressCheckout request.

Character length and limitations: 127 single-byte alphanumeric characters

MAXFAILEDPAYMENTS

(Optional) Number of scheduled payments that can fail before the profile is automatically suspended. An IPN message is sent to the merchant when the specified number of failed payments is reached.

Character length and limitations: Number string representing an integer

AUTOBILLOUTAMT

(Optional) Indicates whether you would like PayPal to automatically bill the outstanding balance amount in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments that have yet to be successfully paid. It is one of the following values:


  • NoAutoBill – PayPal does not automatically bill the outstanding balance.

  • AddToNextBilling – PayPal automatically bills the outstanding balance.

Billing Period Details Fields

Field Description

BILLINGPERIOD

(Required) Unit for billing during this subscription period. It is one of the following values:


  • Day

  • Week

  • SemiMonth

  • Month

  • Year

For SemiMonth, billing is done on the 1st and 15th of each month.

Note The combination of BillingPeriod and BillingFrequency cannot exceed one year.

BILLINGFREQUENCY

(Required) Number of billing periods that make up one billing cycle.

The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing frequency is 52.

Note If the billing period is SemiMonth, the billing frequency must be 1.

TOTALBILLINGCYCLES

(Optional) Number of billing cycles for payment period.


  • For the regular payment period, if no value is specified or the value is 0, the regular payment period continues until the profile is canceled or deactivated.

  • For the regular payment period, if the value is greater than 0, the regular payment period will expire after the trial period is finished and continue at the billing frequency for TotalBillingCycles cycles.

AMT

(Required) Billing amount for each billing cycle during this payment period. This amount does not include shipping and tax amounts.

Note All amounts in the CreateRecurringPaymentsProfile request must have the same currency.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

TRIALBILLINGPERIOD

Unit for billing during this subscription period; required if you specify an optional trial period. It is one of the following values:

  • Day

  • Week

  • SemiMonth

  • Month

  • Year

For SemiMonth, billing is done on the 1st and 15th of each month.

Note The combination of BillingPeriod and BillingFrequency cannot exceed one year.

TRIALBILLINGFREQUENCY

Number of billing periods that make up one billing cycle; required if you specify an optional trial period.

The combination of billing frequency and billing period must be less than or equal to one year. For example, if the billing cycle is Month, the maximum value for billing frequency is 12. Similarly, if the billing cycle is Week, the maximum value for billing frequency is 52.

Note If the billing period is SemiMonth, the billing frequency must be 1.

TRIALTOTALBILLINGCYCLES

(Optional) Number of billing cycles for trial payment period.

TRIALAMT

Billing amount for each billing cycle during this payment period; required if you specify an optional trial period. This amount does not include shipping and tax amounts.

Note All amounts in the CreateRecurringPaymentsProfile request must have the same currency.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

CURRENCYCODE

(Required) Currency code (default is USD).

Character length and limitations: 3 single-byte characters

SHIPPINGAMT

(Optional) Shipping amount for each billing cycle during this payment period.

Note All amounts in the request must have the same currency.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

TAXAMT

(Optional) Tax amount for each billing cycle during this payment period.

Note All amounts in the request must have the same currency.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

Activation Details Fields

Field Description

INITAMT

(Optional) Initial non-recurring payment amount due immediately upon profile creation. Use an initial amount for enrolment or set-up fees.

Note All amounts included in the request must have the same currency.

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

FAILEDINITAMTACTION

(Optional) Action you can specify when a payment fails. It is one of the following values:


  • ContinueOnFailure – By default, PayPal suspends the pending profile in the event that the initial payment amount fails. You can override this default behavior by setting this field to ContinueOnFailure. Then, if the initial payment amount fails, PayPal adds the failed payment amount to the outstanding balance for this recurring payment profile.

    When you specify ContinueOnFailure, a success code is returned to you in the CreateRecurringPaymentsProfile response and the recurring payments profile is activated for scheduled billing immediately. You should check your IPN messages or PayPal account for updates of the payment status.

  • CancelOnFailure – If this field is not set or you set it to CancelOnFailure, PayPal creates the recurring payment profile, but places it into a pending status until the initial payment completes. If the initial payment clears, PayPal notifies you by IPN that the pending profile has been activated. If the payment fails, PayPal notifies you by IPN that the pending profile has been canceled.

Ship To Address Fields

Field Description

SHIPTONAME

Person's name associated with this shipping address. It is required if using a shipping address.

Character length and limitations: 32 single-byte characters

SHIPTOSTREET

First street address. It is required if using a shipping address.

Character length and limitations: 100 single-byte characters

SHIPTOSTREET2

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

SHIPTOCITY

Name of city. It is required if using a shipping address.

Character length and limitations: 40 single-byte characters

SHIPTOSTATE

State or province.
It is required if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. PayPal accepts State codes for some countries.

Character length and limitations: 40 single-byte characters

SHIPTOZIP

U.S. ZIP code or other country-specific postal code. It is required if using a U.S. shipping address; may be required for other countries.

Character length and limitations: 20 single-byte characters

SHIPTOCOUNTRY

Country code. It is required if using a shipping address.

Character length and limitations: 2 single-byte characters

SHIPTOPHONENUM

(Optional) Phone number.

Character length and limitations: 20 single-byte characters

Credit Card Details Fields

Field Description

CREDITCARDTYPE

(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover, and Visa are allowable. For Canada, only MasterCard and Visa are allowable and Interac debit cards are not supported. It is one of the following values:


  • Visa

  • MasterCard

  • Discover

  • Amex

  • Maestro: See note.

Note If the credit card type is Maestro, you must set CURRENCYCODE to GBP. In addition, you must specify either STARTDATE or ISSUENUMBER.

Character length and limitations: Up to 10 single-byte alphabetic characters

ACCT

(Required) Credit card number.

Character length and limitations: Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type.

EXPDATE

Credit card expiration date. This field is required if you are using recurring payments with direct payments.

Character length and limitations: 6 single-byte alphanumeric characters, including leading zero, in the format MMYYYY

CVV2

Card Verification Value, version 2. Your Merchant Account settings determine whether this field is required. To comply with credit card processing regulations, you must not store this value after a transaction has been completed.

Character length and limitations: For Visa, MasterCard, and Discover, the value is exactly 3 digits. For American Express, the value is exactly 4 digits.

STARTDATE

(Optional) Month and year that Maestro card was issued.

Character length and limitations: Must be 6 digits, including leading zero, in the format MMYYYY

ISSUENUMBER

(Optional) Issue number of Maestro card.

Character length and limitations: 2 numeric digits maximum

Payer Information Fields

Field Description

EMAIL

(Required) Email address of buyer.

Character length and limitations: 127 single-byte characters

PAYERID

(Optional) Unique PayPal Customer Account identification number.

Character length and limitations:13 single-byte alphanumeric characters

PAYERSTATUS

(Optional) Status of buyer. It is one of the following values:


  • verified

  • unverified

Character length and limitations: 10 single-byte alphabetic characters

COUNTRYCODE

(Optional) Buyer's country of residence in the form of ISO standard 3166 two-character country codes.

Character length and limitations: 2 single-byte characters

BUSINESS

(Optional) Buyer's business name.

Character length and limitations: 127 single-byte characters

Payer Name Fields

Field Description

SALUTATION

(Optional) Buyer's salutation.

Character length and limitations: 20 single-byte characters

FIRSTNAME

(Optional) Buyer's first name.

Character length and limitations: 25 single-byte characters

MIDDLENAME

(Optional) Buyer's middle name.

Character length and limitations: 25 single-byte characters

LASTNAME

(Optional) Buyer's last name.

Character length and limitations: 25 single-byte characters

SUFFIX

(Optional) Buyer's suffix.

Character length and limitations: 12 single-byte characters

Address Fields

Field Description

STREET

(Required) First street address.

Character length and limitations: 100 single-byte characters

STREET2

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CITY

(Required) Name of city.

Character length and limitations: 40 single-byte characters

STATE

(Required) State or province.

Character length and limitations: 40 single-byte characters

COUNTRYCODE

(Required) Country code.

Character length and limitations: 2 single-byte characters

ZIP

(Required) U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

SHIPTOPHONENUM

(Optional) Phone number.

Character length and limitations: 20 single-byte characters

Payment Details Item Fields

Field Description

L_PAYMENTREQUEST_n_ITEMCATEGORYm

Indicates whether the item is digital or physical. For digital goods, this field is required and must be set to Digital to get the best rates. Is one of the following values. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_ITEMCATEGORY0, L_PAYMENTREQUEST_n_ITEMCATEGORY1). Is one of the following values:


  • Digital

  • Physical

This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_NAMEm

Item name. This field is required when ItemCategory is passed.

Item name. This field is required when L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NAME0, L_PAYMENTREQUEST_n_NAME1).

Character length and limitations: 127 single-byte characters

This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_DESCm

(Optional) Item description. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_DESC0, L_PAYMENTREQUEST_n_DESC1).

Character length and limitations: 127 single-byte characters

This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_AMTm

Cost of item. This field is required when ItemCategory is passed.

Cost of item. This field is required when L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_AMT0, L_PAYMENTREQUEST_n_AMT1).

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_NUMBERm

(Optional) Item number. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_NUMBER0, L_PAYMENTREQUEST_n_NUMBER1).

Character length and limitations: 127 single-byte characters

This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_QTYm

Item quantity. This field is required when ItemCategory is passed.

Item quantity. This field is required when L_PAYMENTREQUEST_n_ITEMCATEGORYm is passed. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_QTY0, L_PAYMENTREQUEST_n_QTY1).

Character length and limitations: Any positive integer

This field is introduced in version 69.0.

L_PAYMENTREQUEST_n_TAXAMTm

(Optional) Item sales tax. These parameters must be ordered sequentially beginning with 0 (for example L_PAYMENTREQUEST_n_TAXAMT0, L_PAYMENTREQUEST_n_TAXAMT1).

Character length and limitations: Value is a positive number which cannot exceed 10,000.00 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

This field is introduced in version 69.0.

CreateRecurringPaymentsProfile Response Message

CreateRecurringPaymentsProfile Response Fields

Field Description

PROFILEID

A unique identifier for future reference to the details of this recurring payment.

Character length and limitations: Up to 14 single-byte alphanumeric characters.

PROFILESTATUS

Status of the recurring payment profile.


  • ActiveProfile – The recurring payment profile has been successfully created and activated for scheduled payments according the billing instructions from the recurring payments profile.

  • PendingProfile – The system is in the process of creating the recurring payment profile. Please check your IPN messages for an update.