CreateRecurringPaymentsProfile API Operation (NVP)
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 |
---|---|
|
(Required) Must be |
|
A timestamped token, the value of which was returned in the response to the first call to Note: Tokens expire after approximately 3 hours. |
Recurring Payments Profile Details Fields
Field | Description |
---|---|
|
(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 double-byte characters |
|
(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, |
|
(Optional) The merchant's own unique reference or invoice number. Character length and limitations: 127 single-byte alphanumeric characters |
Schedule Details Fields
Field | Description |
---|---|
|
(Required) Description of the recurring payment. Note: You must ensure that this field matches the corresponding billing agreement description included in the
Character length and limitations: 127 single-byte alphanumeric characters |
|
(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 |
|
(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. Value is:
|
Billing Period Details Fields
Field | Description |
---|---|
|
(Required) Unit for billing during this subscription period. Value is:
For Note: The combination of |
|
(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 Note: If the billing period is
|
|
(Optional) Number of billing cycles for payment period.
|
|
(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
Character length and limitations: Value is typically a positive number that cannot exceed |
|
Unit for billing during this subscription period; required if you specify an optional trial period. Value is:
For Note: The combination of |
|
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 Note: If the billing period is
|
|
(Optional) Number of billing cycles for trial payment period. |
|
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
Character length and limitations: Value is typically a positive number that cannot exceed |
|
(Required) Currency code (default is USD). Character length and limitations: 3 single-byte characters |
|
(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 typically a positive number that cannot exceed |
|
(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 typically a positive number that cannot exceed |
Activation Details Fields
Field | Description |
---|---|
|
(Optional) Initial non-recurring payment amount due immediately upon profile creation. Use an initial amount for enrollment or setup fees. Note: All amounts included in the request must have the same currency. Character length and limitations: Value is typically a positive number that cannot exceed |
|
(Optional) Action you can specify when a payment fails. Value is:
|
Ship To Address Fields
Field | Description |
|
Person's name associated with this shipping address. It is required if using a shipping address. Character length and limitations: 32 double-byte characters |
---|---|
|
First street address. It is required if using a shipping address. Character length and limitations: 100 single-byte characters |
|
(Optional) Second street address. Character length and limitations: 100 single-byte characters |
|
Name of city. It is required if using a shipping address. Character length and limitations: 40 single-byte characters |
|
State or province.
It is required for transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. See the list of PayPal State codes. Character length and limitations: 40 single-byte characters |
|
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 |
|
Country code. It is required if using a shipping address. Character length and limitations: 2 single-byte characters |
|
(Optional) Phone number. Character length and limitations: 20 single-byte characters |
Credit Card Details Fields
Payer Information Fields
Field | Description |
---|---|
|
(Required) Email address of buyer. Character length and limitations: 127 single-byte characters |
|
(Optional) Unique PayPal Customer Account identification number. Character length and limitations:13 single-byte alphanumeric characters |
|
(Optional) Status of buyer. Value is:
Character length and limitations: 10 single-byte alphabetic characters |
|
(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 |
|
(Optional) Buyer's business name. Character length and limitations: 127 single-byte characters |
Payer Name Fields
Field | Description |
---|---|
|
(Optional) Buyer's salutation. Character length and limitations: 20 single-byte characters |
|
(Optional) Buyer's first name. Character length and limitations: 64 double-byte characters |
|
(Optional) Buyer's middle name. Character length and limitations: 64 double-byte characters |
|
(Optional) Buyer's last name. Character length and limitations: 64 double-byte characters |
|
(Optional) Buyer's suffix. Character length and limitations: 12 single-byte characters |
Address Fields
Field | Description |
---|---|
|
(Required) First street address. Character length and limitations: 100 single-byte characters |
|
(Optional) Second street address. Character length and limitations: 100 single-byte characters |
|
(Required) Name of city. Character length and limitations: 40 single-byte characters |
|
(Required) State or province. Character length and limitations: 40 single-byte characters |
|
(Required) Country code. Character length and limitations: 2 single-byte characters |
|
(Required) U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters |
|
(Optional) Phone number. Character length and limitations: 20 single-byte characters |
SOFTDESCRIPTOR |
(Optional) Information that is usually displayed in the account holder's statement, for example, Character length and limitations: 23 alphanumeric characters, can include the special characters dash (
|
SOFTDESCRIPTORCITY |
(Optional) A unique phone number, email address or URL, which is displayed on the account holder's statement. PayPal recommends passing a toll-free phone number because, typically, this is the easiest way for a buyer to contact the seller in the case of an inquiry. If it includes the space character (
Added in version 115 of the API. |
Payment Details Item Fields
Field | Description |
---|---|
|
Indicates whether the item is digital or physical. For digital goods, this field is required and must be set to
This field is introduced in version 69.0. |
|
Item name. This field is required when Item name. This field is required when Character length and limitations: 127 single-byte characters This field is introduced in version 69.0. |
|
(Optional) Item description. These parameters must be ordered sequentially beginning with 0 (for example Character length and limitations: 127 single-byte characters This field is introduced in version 69.0. |
|
Cost of item. This field is required when Cost of item. This field is required when Character length and limitations: Value is typically a positive number that cannot exceed This field is introduced in version 69.0. |
|
(Optional) Item number. These parameters must be ordered sequentially beginning with 0 (for example Character length and limitations: 127 single-byte characters This field is introduced in version 69.0. |
|
Item quantity. This field is required when Item quantity. This field is required when Character length and limitations: Any positive integer This field is introduced in version 69.0. |
|
(Optional) Item sales tax. These parameters must be ordered sequentially beginning with 0 (for example Character length and limitations: Value is typically a positive number that cannot exceed This field is introduced in version 69.0. |
3-D Secure Request Fields (UK Merchants Only)
Note: When PayPal implements 3-D Secure authentication for recurring payments in September 2019, the following 3-D Secure fields will be added:
Field | Description |
---|---|
AUTHSTATUS3DS |
(Optional) A value returned by CardinalCommerce. If the cmpi_lookup request returns Y for Enrolled , set this field to the PAResStatus value returned by cmpi_authenticate . Otherwise, set this field to blank. |
MPIVENDOR3DS |
(Optional) A value returned by CardinalCommerce. Set this field to the Enrolled value returned by cmpi_lookup . |
CAVV |
(Optional) A value returned by CardinalCommerce. If the cmpi_lookup request returns Y for Enrolled , set this field to the Cavv value returned by cmpi_authenticate . Otherwise, set this field to blank. |
ECI3DS |
(Optional) A value returned by CardinalCommerce. If the cmpi_lookup request returns Y for Enrolled , set this field to the EciFlag value returned by cmpi_authenticate . Otherwise, set this field to the EciFlag value returned by cmpi_lookup . |
XID |
(Optional) A value returned by CardinalCommerce. If the cmpi_lookup request returns Y for Enrolled , set this field to the Xid value returned by cmpi_authenticate . Otherwise, set this field to blank. |
THREEDSVERSION |
This field is for 3-D Secure 2.0. Contains the 3DS version that was used to process the transaction. Possible values:
|
DSTRANSACTIONID |
This field is for 3-D Secure 2.0. Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. Note: Required for Mastercard Identity Check transaction in Authorization. Available only in EMV 3DS (3DS 2.0) transactions. |
Related information: 3-D Secure with Cardinal Cruise
CreateRecurringPaymentsProfile Response Message
CreateRecurringPaymentsProfile Response Fields
Field | Description |
---|---|
|
A unique identifier for future reference to the details of this recurring payment. Character length and limitations: Up to 14 single-byte alphanumeric characters. |
|
Status of the recurring payment profile.
|
|
The transaction ID from the direct credit card initial payment. Character length and limitations: 17 characters except for transactions of the Order type have a character length of 19. |