This article is for the Hosted Payment Method Pages 1.0. Payment Pages 2.0 are now generally available, and are a replacement for the Hosted Payment Method Pages 1.0. Please consider using Payment Pages 2.0, as there are no further plans for Hosted Payment Method Pages 1.0.
There are two ways to associate a payment method to a Zuora account:
- Use the Subscribe API call to link a payment method to a newly created Zuora account
- Add a newly created payment method to an existing Zuora account
A payment method must be tied to a Zuora account using the methods below. An orphan payment method will be deleted if it is not associated with a Zuora account within a defined lifespan. As of release R188, the defined time limit is 240 hours.
Use the Payment Method in a Subscribe API Call
RefId returned from a successful Hosted Payment Method pages submission is the same as the payment method ID. Enter this ID for the payment method object in a
subscribe() call when you create a new subscription.
For example within the subscribe call you would enter:
<ns1:PaymentMethod> <ns2:Id>[RefID returned from Zuora]</ns2:Id> </ns1:PaymentMethod>
How Zuora uses the ID depends on whether you are calling
subscribe() on a new or existing account:
- For a new account, if you pass in a payment method ID, Zuora associates the newly created account with this payment method ID. This payment method is set as the default for the account and therefore will be used for subsequent payments on the account.
- For an existing account, if you pass in a payment method ID, Zuora associates the payment method with the account, and the payment method is used for this payment. However, this payment method is not be set as the default for the account, so the newly created payment method will not be applied to subsequent payments.
subscribe call is the only way to link a Hosted Payment Method page's payment method to a newly created Zuora account. You cannot create a payment method with the Hosted Payment Method page and then update the AccountID in the payment method object via the API.
If the payment method ID is not submitted in the
subscribe call or the ID is invalid, Zuora does not attempt to validate that the rest of the fields are available, including credit card number and cardholder name, to create a payment method in the call.
Create a Payment Method for an Existing Account
To create or add a payment method to an existing account, append the field
field_accountId to the iFrame request. See Customizing Hosted Payment Method pages for information about pre-loading data.
For example, to add a payment method to a customer account having the account id,
4028e69633f7e23b0133fc473bf141a5, you would append the following to the Hosted Payment Method page URL request:
The newly created payment method will not be made default on the account. You will need to use the Zuora API to update the account to set this payment method as default.
You must use the Zuora API to update card expiration dates and retrieve, display, and delete credit card information.