> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://zuora.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server. # Retrieve the default payment method of an account GET https://rest.test.zuora.com/v1/accounts/{account-key}/payment-methods/default Retrieves the default payment method of the specified customer account. **Notes:** This operation also supports retrieving the custom payment method created through the [Open Payment Method](https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/MB_Set_up_custom_payment_gateways_and_payment_methods) service. This operation only works with an electronic payment method and does not work with non-electronic payment methods. Reference: https://zuora.ferndocs.com/developers/api-reference/zuora-api/customer-accounts/accounts/get-acount-default-payment-method ## Authentication - `Authorization` header (bearer token, required) — Use `Bearer {{token}}` in the `Authorization` header for authentication. ## Servers - `https://rest.test.zuora.com` (US Developer & Central Sandbox (incl. Test Drive), default) - `https://rest.sandbox.na.zuora.com` (US API Sandbox Cloud 1) - `https://rest.apisandbox.zuora.com` (US API Sandbox Cloud 2) - `https://rest.na.zuora.com` (US Production Cloud 1) - `https://rest.zuora.com` (US Production Cloud 2) - `https://rest.test.eu.zuora.com` (EU Developer & Central Sandbox) - `https://rest.sandbox.eu.zuora.com` (EU API Sandbox) - `https://rest.eu.zuora.com` (EU Production) - `https://rest.test.ap.zuora.com` (APAC Developer & Central Sandbox) - `https://rest.ap.zuora.com` (APAC Production) ## Request ### Path parameters - `account-key` (string, required) — Account number or account ID. ### Headers - `Accept-Encoding` (string, optional) — Include the `Accept-Encoding: gzip` header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a `Content-Encoding` header with the compression algorithm so that your client can decompress it. - `Content-Encoding` (string, optional) — Include the `Content-Encoding: gzip` header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload. - `Zuora-Track-Id` (string, optional) — A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue. The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (`:`), semicolon (`;`), double quote (`"`), and quote (`'`). - `Zuora-Entity-Ids` (string, optional) — An entity ID. If you have [Zuora Multi-entity](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Multi-entity) enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header. - `Zuora-Org-Ids` (string, optional) — Comma separated IDs. If you have Zuora Multi-Org enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header. The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs. - `Zuora-Version` (string, optional) — The minor API version. For a list of available minor versions, see [API upgrades](https://developer.zuora.com/v1-api-reference/api-upgrades/). ## Response ### 200 OK - `accountHolderInfo` (GETAccountPMAccountHolderInfo, optional) — The account holder information. - `accountVerificationService` (string, optional) — Displays the name of the service provider. For example, Plaid. - `accountVerificationStatus` (enum, optional) — Displays the status of the account. **Note:** - `Active` - Access token is active. - `Expired` - Access token has expired and must be linked again. - `Expiring` - Access token will expire in few days(7 days for Plaid) and must be linked again - `Inactive` - The end customer has revoked the account pemission. The end customer can login again and select the same method for the access token to be linked again. - Allowed values: `Active`, `Expired`, `Expiring`, `Inactive` - `bankIdentificationNumber` (string, optional) — The first six or eight digits of the payment method's number, such as the credit card number or account number. Banks use this number to identify a payment method. - `createdBy` (string, optional) — ID of the user who created this payment method. - `createdOn` (datetime, optional) — The date and time when the payment method was created, in `yyyy-mm-dd hh:mm:ss` format. - `cardNumber` (string, optional) — The masked credit card number. When `cardNumber` is `null`, the following fields will not be returned: - `expirationMonth` - `expirationYear` - `accountHolderInfo` - `creditCardType` (string, optional) — The type of the credit card or debit card. Possible values include `Visa`, `MasterCard`, `AmericanExpress`, `Discover`, `JCB`, and `Diners`. For more information about credit card types supported by different payment gateways, see [Supported Payment Gateways](https://knowledgecenter.zuora.com/CB_Billing/M_Payment_Gateways/Supported_Payment_Gateways). **Note:** This field is only returned for the Credit Card and Debit Card payment types. - `deviceSessionId` (string, optional) — The session ID of the user when the `PaymentMethod` was created or updated. - `existingMandate` (enum, optional) — Indicates whether the mandate is an existing mandate. - Allowed values: `Yes`, `No` - `id` (string, optional) — The payment method ID. - `ipAddress` (string, optional) — The IP address of the user when the payment method was created or updated. - `isDefault` (boolean, optional) — Indicates whether this payment method is the default payment method for the account. - `lastFailedSaleTransactionDate` (string, optional) — The date of the last failed attempt to collect payment with this payment method. - `lastTransaction` (string, optional) — Indicates the occurrence and status of the last transaction. - `lastTransactionTime` (datetime, optional) — The time when the last transaction of this payment method happened. - `mandateInfo` (POSTAccountPMMandateInfo, optional) — The mandate information for the Credit Card, Apple Pay, Google Pay, Credit Card Reference Transaction, ACH, or Bank Transfer payment method. The following mandate fields are common to all supported payment methods: * `mandateId` * `mandateReason` * `mandateStatus` The following mandate fields are specific to the ACH and Bank Transfer payment methods: * `mandateReceivedStatus` * `existingMandateStatus` * `mandateCreationDate` * `mandateUpdateDate` The following mandate fields are specific to the Credit Card, Apple Pay, and Google Pay payment methods: * `mitTransactionId` * `mitProfileAgreedOn` * `mitConsentAgreementRef` * `mitConsentAgreementSrc` * `mitProfileType` * `mitProfileAction` - `maxConsecutivePaymentFailures` (integer, optional) — The number of allowable consecutive failures Zuora attempts with the payment method before stopping. - `numConsecutiveFailures` (integer, optional) — The number of consecutive failed payments for this payment method. It is reset to `0` upon successful payment. - `paymentRetryWindow` (integer, optional) — The retry interval setting, which prevents making a payment attempt if the last failed attempt was within the last specified number of hours. - `secondTokenId` (string, optional) — A gateway unique identifier that replaces sensitive payment method data. **Note:** This field is only returned for the Credit Card Reference Transaction payment type. - `status` (enum, optional) — The status of the payment method. - Allowed values: `Active`, `Closed`, `Scrubbed` - `tokenId` (string, optional) — A gateway unique identifier that replaces sensitive payment method data or represents a gateway's unique customer profile. **Note:** This field is only returned for the Credit Card Reference Transaction payment type. - `totalNumberOfErrorPayments` (integer, optional) — The number of error payments that used this payment method. - `totalNumberOfProcessedPayments` (integer, optional) — The number of successful payments that used this payment method. - `type` (enum, optional) — The type of the payment method. - Allowed values: `CreditCard`, `CreditCardReferenceTransaction`, `ACH`, `SEPA`, `Betalingsservice`, `Autogiro`, `Bacs`, `Becs`, `Becsnz`, `PAD`, `PayPalCP`, `PayPalEC`, `PayPalNativeEC`, `PayPalAdaptive`, `AdyenApplePay`, `AdyenGooglePay`, `GooglePay` - `updatedBy` (string, optional) — ID of the user who made the last update to this payment method. - `updatedOn` (datetime, optional) — The last date and time when the payment method was updated, in `yyyy-mm-dd hh:mm:ss` format. - `useDefaultRetryRule` (boolean, optional) — Indicates whether this payment method uses the default retry rules configured in the Zuora Payments settings. - `IBAN` (string, optional) — The International Bank Account Number used to create the SEPA payment method. The value is masked. - `accountNumber` (string, optional) — The number of the customer's bank account and it is masked. - `bankCode` (string, optional) — The sort code or number that identifies the bank. This is also known as the sort code. - `bankTransferType` (string, optional) — The type of the Bank Transfer payment method. For example, `SEPA`. - `branchCode` (string, optional) — The branch code of the bank used for Direct Debit. - `businessIdentificationCode` (string, optional) — The BIC code used for SEPA. The value is masked. - `identityNumber` (string, optional) — The identity number of the account holder or the cardholder. - `bankABACode` (string, optional) — The nine-digit routing number or ABA number used by banks. This field is only required if the `type` field is set to `ACH`. - `bankAccountName` (string, optional) — The name of the account holder, which can be either a person or a company. This field is only required if the `type` field is set to `ACH`. - `expirationMonth` (integer, optional) — One or two digits expiration month (1-12). - `expirationYear` (integer, optional) — Four-digit expiration year. - `securityCode` (string, optional) — The CVV or CVV2 security code for the credit card or debit card. Only required if changing expirationMonth, expirationYear, or cardHolderName. To ensure PCI compliance, this value isn''t stored and can''t be queried. - `BAID` (string, optional) — ID of a PayPal billing agreement. For example, I-1TJ3GAGG82Y9. - `email` (string, optional) — Email address associated with the PayPal payment method. - `preapprovalKey` (string, optional) — The PayPal preapproval key. - `googleBIN` (string, optional) — This field is only available for Google Pay payment methods. - `googleCardNumber` (string, optional) — This field is only available for Google Pay payment methods. - `googleCardType` (string, optional) — This field is only available for Google Pay payment methods. For Google Pay payment methods on Adyen, the first 100 characters of [paymentMethodVariant](https://docs.adyen.com/development-resources/paymentmethodvariant) returned from Adyen are stored in this field. - `googleExpiryDate` (string, optional) — This field is only available for Google Pay payment methods. - `googleGatewayToken` (string, optional) — This field is only available for Google Pay payment methods. - `appleBIN` (string, optional) — This field is only available for Apple Pay payment methods. - `appleCardNumber` (string, optional) — This field is only available for Apple Pay payment methods. - `appleCardType` (string, optional) — This field is only available for Apple Pay payment methods. For Apple Pay payment methods on Adyen, the first 100 characters of [paymentMethodVariant](https://docs.adyen.com/development-resources/paymentmethodvariant) returned from Adyen are stored in this field. - `appleExpiryDate` (string, optional) — This field is only available for Apple Pay payment methods. - `appleGatewayToken` (string, optional) — This field is only available for Apple Pay payment methods. ## Errors ### 500 Internal Server Error Internal Server Error - `reasons` (list of ErrorResponseReasonsItems, optional) ### 400 Client Request Error Request Errors - `processId` (string, optional) — The ID of the process that handles the operation. - `reasons` (list of CommonResponseReasonsItems, optional) — The container of the error code and message. This field is available only if the `success` field is `false`. - `requestId` (string, optional) — Unique identifier of the request. - `success` (boolean, optional) — Indicates whether the call succeeded. ## Types ### GETAccountPMAccountHolderInfo The account holder information. - `accountHolderName` (string, optional) — The full name of the account holder. - `addressLine1` (string, optional) — The first line of the address for the account holder. - `addressLine2` (string, optional) — The second line of the address for the account holder. - `city` (string, optional) — The city where the account holder stays. - `country` (string, optional, nullable) — The country where the account holder stays. When creating a payment method through a translated UI or Payment Page, a country name in a translated language might be selected. Regardless of the country texts selected when creating the payment method, only the supported country name returns in this field. For a complete list of supported country names, see View countries or regions. Internationalization is not supported for the API field value. - `email` (string, optional) — The email address of the account holder. - `phone` (string, optional) — The phone number of the account holder. - `state` (string, optional) — The state where the account holder stays. - `zipCode` (string, optional) — The zip code for the address of the account holder. ### POSTAccountPMMandateInfo The mandate information for the Credit Card, Apple Pay, Google Pay, Credit Card Reference Transaction, ACH, or Bank Transfer payment method. The following mandate fields are common to all supported payment methods: * `mandateId` * `mandateReason` * `mandateStatus` The following mandate fields are specific to the ACH and Bank Transfer payment methods: * `mandateReceivedStatus` * `existingMandateStatus` * `mandateCreationDate` * `mandateUpdateDate` The following mandate fields are specific to the Credit Card, Apple Pay, and Google Pay payment methods: * `mitTransactionId` * `mitProfileAgreedOn` * `mitConsentAgreementRef` * `mitConsentAgreementSrc` * `mitProfileType` * `mitProfileAction` - `existingMandateStatus` (enum, optional) — Indicates whether the mandate is an existing mandate. - Allowed values: `Yes`, `No` - `mandateCreationDate` (date, optional) — The date on which the mandate was created. - `mandateId` (string, optional) — The mandate ID. - `mandateReason` (string, optional) — The reason of the mandate from the gateway side. - `mandateReceivedStatus` (enum, optional) — Indicates whether the mandate is received from the gateway - Allowed values: `Yes`, `No` - `mandateStatus` (string, optional) — The status of the mandate from the gateway side. - `mandateUpdateDate` (date, optional) — The date on which the mandate was updated. - `mitConsentAgreementRef` (string, optional) — Reference for the consent agreement that you have established with the customer. - `mitConsentAgreementSrc` (enum, optional) — Required if you set the `mitProfileAction` field. Specify how the consent agreement has been established with the customer. The allowed value is `External`. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `External` set to this field. - Allowed values: `External` - `mitProfileAction` (enum, optional) — Specifies how Zuora creates and activates the stored credential profile. Only applicable if you set the `status` field to `Active`. * `Activate` (default) - Use this value if you are creating the stored credential profile after receiving the customer's consent. Zuora will create the stored credential profile then send a cardholder-initiated transaction (CIT) to the payment gateway to validate the stored credential profile. If the CIT succeeds, the status of the stored credential profile will be `Active`. If the CIT does not succeed, Zuora will not create a stored credential profile. If the payment gateway does not support the stored credential transaction framework, the status of the stored credential profile will be `Agreed`. * `Persist` - Use this value if the stored credential profile represents a stored credential profile in an external system. The status of the payment method's stored credential profile will be `Active`. If you do not specify this field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Activate` set to this field. - Allowed values: `Activate`, `Persist` - `mitProfileAgreedOn` (date, optional) — The date on which the stored credential profile is agreed. The date format is `yyyy-mm-dd`. - `mitProfileType` (string, optional) — Indicates the type of the stored credential profile. If you do not specify the `mitProfileAction` field, Zuora will automatically create a stored credential profile for the payment method, with the default value `Recurring` set to this field. - `mitTransactionId` (string, optional) — Specifies the ID of the transaction. Only applicable if you set the `mitProfileAction` field to `Persist`. ### ErrorResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ### CommonResponseReasonsItems - `code` (string, optional) — The error code of response. - `message` (string, optional) — The detail information of the error response ## Examples **Response** ```json { "accountHolderInfo": { "accountHolderName": "John Smith", "addressLine1": "ABC", "addressLine2": "EFT", "city": "Example City", "country": "United States", "email": "example@google.com", "phone": "86123456789", "state": "Example State", "zipCode": "844000" }, "bankIdentificationNumber": "411111", "createdBy": "402881e522cf4f9b0122cf5d82860002", "cardNumber": "************1111", "creditCardType": "Visa", "deviceSessionId": null, "existingMandate": null, "id": "4028839f7d26a155017d26af16ef0001", "ipAddress": null, "isDefault": true, "lastFailedSaleTransactionDate": null, "lastTransaction": "Approved", "mandateInfo": {}, "maxConsecutivePaymentFailures": null, "numConsecutiveFailures": 0, "paymentRetryWindow": null, "status": "Active", "totalNumberOfErrorPayments": 0, "totalNumberOfProcessedPayments": 0, "type": "CreditCard", "updatedBy": "402881e522cf4f9b0122cf5d82860002", "useDefaultRetryRule": true, "identityNumber": "97370192024", "expirationMonth": 11, "expirationYear": 2027, "AA_PICKLIST__c": null, "accountKey": "4028839f7ca29000017ca29c1ce8003f", "createdDate": "2021-11-15 18:59:08", "lastTransactionDateTime": "2021-11-15 18:59:08", "lastTransactionStatus": "Approved", "success": true, "updatedDate": "2021-11-15 18:59:08" } ``` **SDK Code** ```python response import requests url = "https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript response const url = 'https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go response package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby response require 'uri' require 'net/http' url = URI("https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java response import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default") .header("Authorization", "Bearer ") .asString(); ``` ```php response request('GET', 'https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp response using RestSharp; var client = new RestClient("https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift response import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rest.test.zuora.com/v1/accounts/account-key/payment-methods/default")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```