GetRecurringPaymentsProfileDetails API Operation (SOAP)

Obtain information about a recurring payments profile.

GetRecurringPaymentsProfileDetails Request Message

GetRecurringPaymentsProfileDetails Request Fields

Field Description

ProfileID

xs:string

(Required) Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response. 19-character profile IDs are supported for compatibility with previous versions of the PayPal API.

Character length and limitations: 14 single-byte alphanumeric characters

GetRecurringPaymentsProfileDetails Response Message

GetRecurringPaymentsProfileDetails Response Fields

Field Description

ProfileID

xs:string

Recurring payments profile ID returned in the CreateRecurringPaymentsProfile response.

ProfileStatus

ns:RecurringPaymentsProfileStatusType

Status of the recurring payment profile. It is one of the following values:

  • Active

  • Pending

  • Cancelled

  • Suspended

  • Expired

Description

xs:string

Description of the recurring payment.

Character length and limitations: 127 single-byte alphanumeric characters

AutoBillOutstandingAmount

ns:AutoBillType

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 amount.

  • AddToNextBilling – PayPal automatically bills the outstanding balance amount.

MaxFailedPayments

xs:int

Number of scheduled payments that can fail before the profile is automatically suspended.

Character length and limitations: Number string representing an integer

RecurringPayments ProfileDetails

ns:RecurringPaymentsProfileDetailsType

Buyer information for this recurring payments profile.

CurrentRecurring PaymentsPeriod

ns:BillingPeriodDetailsType

Details of the current subscription period. This field is not returned if the profile is canceled or expired.

RecurringPayments Summary

ns:RecurringPaymentsSummaryDetailsType

Payment summary for this recurring payments profile.

AggregateAmount

ns:AmountType

Total amount collected thus far for scheduled payments.

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.

AggregateOptionalAmount

ns:AmountType

Total amount collected thus far for optional payments.

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.

FinalPaymentDueDate

ns:DateTime

Final scheduled payment due date before the profile expires.

CreditCard

ns:CreditCardDetailsType

If this is a recurring payments profile using direct payments, this field contains the credit card information for this profile.

Note Only the last 4 digits of the credit card account number are returned. The CVV2 value is not returned.

RecurringPaymentsProfileDetailsType Fields

Field Description

SubscriberName

xs:string

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.

SubscriberShipping Address

ns:AddressType

The subscriber's shipping address associated with this profile, if applicable. If you do not specify it, the ship-to address from buyer's PayPal account is used.

Note Shipping Address is optional, but if you include it, you are required to pass certain fields.

BillingStartDate

xs:dateTime

The date when billing for this profile begins.

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

Character length and limitations: Date and time are in UTC/GMT format; for example, 2013-08-24T05:38:48Z.

ProfileReference

xs:string

The merchant's own unique reference or invoice number.

Character length and limitations: 127 single-byte alphanumeric characters.

AddressType (Shipping) Fields

Field Description

addressStatus

ebl:addressStatusTypeCode

Status of street address on file with PayPal. It is one of the following values:

  • none

  • Confirmed

  • Unconfirmed

Name

xs:string

Person's name associated with this address.

Character length and limitations: 32 single-byte characters

Street1

xs:string

First street address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

Name of city.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

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

PostalCode

xs:string

U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

Country

ebl:CountryCode

Country code.

Character length and limitations: 2 single-byte characters

Note If the country is China, this field will return CN.

BillingPeriodDetailsType Fields

Field Description

BillingPeriod

ns:BillingPeriodType

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

xs:int

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

xs:int

Number of billing cycles for payment period (either the regular payment period or the trial period).

  • For the trial period, the value must be greater than 0.

  • 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.

Amount

cc:BasicAmountType

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.

ShippingAmount

cc:BasicAmountType

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.

TaxAmount

cc:BasicAmountType

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.

RecurringPaymentsSummaryDetailsType Fields

Field Description

NextBillingDate

xs:dateTime

The next scheduled billing date, in YYYY-MM-DD format.

NumberCycles Completed

xs:int

The number of billing cycles completed in the current active subscription period. A billing cycle is considered completed when payment is collected or after retry attempts to collect payment for the current billing cycle have failed.

NumberCycles Remaining

xs:int

The number of billing cycles remaining in the current active subscription period.

OutstandingBalance

cc:BasicAmountType

The current past due or outstanding balance for this profile.

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.

FailedPaymentCount

xs:int

The total number of failed billing cycles for this profile.

LastPaymentDate

xs:dateTime

The date of the last successful payment received for this profile, in YYYY-MM-DD format.

LastPaymentAmount

cc:BasicAmountType

The amount of the last successful payment received for this profile.

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.

CreditCardDetailsType Fields

Field Description

CreditCardType

ebl:CreditCardType

Type of credit card. Is one of the following values:

  • Visa

  • MasterCard

  • Discover

  • Amex

  • Maestro – See note.

Note If the credit card type is Maestro, you must set the currencyId to GBP. In addition, you must specify either StartMonth and StartYear or IssueNumber.

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

CreditCardNumber

xs:string

Credit card number. Only the last 4 digits of the credit card number are returned.

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.

ExpMonth

xs:int

Credit card expiration month.

Character length and limitations: 2 single-byte numeric characters, including leading zero

ExpYear

xs:int

Credit card expiration year.

Character length and limitations: 4 single-byte numeric characters

CardOwner

ns:PayerInfoType

Details about the owner of the credit card.

StartMonth

xs:int

Month that Maestro card was issued.

Character length and limitations: 2-digit, zero-filled if necessary

StartYear

xs:int

Year that Maestro card was issued.

Character length and limitations: 4 digits

IssueNumber

xs:string

Issue number of Maestro card.

Character length and limitations: 2 numeric digits

PayerInfoType Fields

Field Description

Payer

ns:EmailAddressType

Email address of buyer.

Character length and limitations: 127 single-byte characters

FirstName

ns:PersonNameType

Buyer's first name.

Character length and limitations: 25 single-byte characters

LastName

ns:PersonNameType

Buyer's last name.

Character length and limitations: 25 single-byte characters

Address

ns:AddressType

Buyer's billing address information.

AddressType Fields

Field Description

AddressOwner

ebl:AddressOwnerTypeCode

eBay company that maintains this address. It is one of the following values:

  • eBay

  • PayPal

addressStatus

ebl:addressStatusTypeCode

Status of street address on file with PayPal. It is one of the following values:

  • none

  • Confirmed

  • Unconfirmed

Name

xs:string

Person's name associated with this address.

Character length and limitations: 32 single-byte characters

Street1

xs:string

First street address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

Name of city.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

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

PostalCode

xs:string

U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

Country

ns:CountryCode

Country code.

Character length and limitations: 2 single-byte characters

CountryName

xs:string

Expanded name of country.

Character length and limitations: 64 single-byte alphanumeric characters

Phone

xs:string

Phone number.

Character length and limitations: 20 single-byte characters