This documentation site is deprecated. The latest up-to-date API reference is available at https://reference.chargify.com.
This site will remain available for historical reference until June 1, 2017

API: Payment Profiles

URI/Method

Resource/URI GET POST PUT DELETE
Payment Profiles
/payment_profiles
Create new payment profile
Payment Profiles
/payment_profiles/<x>
Read payment profile Update payment profile

Payment Profile Input Attributes

  • payment_profile
    • payment_type (Optional) Default is credit_card. May be bank_account or credit_card or paypal_account.
    • customer_id (Required when creating a new payment profile) The Chargify customer id.
    • first_name First name on card or bank account.
    • last_name Last name on card or bank account.
    • full_number (Required when payment_type is credit_card unless you provide the vault_token) The full credit card number (string representation, i.e. “5424000000000015”)
    • expiration_month (Required when payment_type is credit_card unless you provide the vault_token) The 1- or 2-digit credit card expiration month, as an integer or string, i.e. “5”
    • expiration_year (Required when payment_type is credit_card unless you provide the vault_token) The 4-digit credit card expiration year, as an integer or string, i.e. “2012”
    • cvv (Optional, may be required by your gateway settings) The 3- or 4-digit Card Verification Value. This value is merely passed through to the payment gateway.
    • billing_address (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing street address (i.e. “123 Main St.”). This value is merely passed through to the payment gateway.
    • billing_address_2 (Optional) Second line of the customer’s billing address i.e. “Apt. 100”
    • billing_city (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address city (i.e. “Boston”). This value is merely passed through to the payment gateway.
    • billing_state (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address state (i.e. “MA”). This value is merely passed through to the payment gateway.
    • billing_zip (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address zip code (i.e. “12345”). This value is merely passed through to the payment gateway.
    • billing_country (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address country, preferably in [ISO 3166-1 alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (i.e. “US”). This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Please check your gateway’s documentation. If creating an ACH subscription, only US is supported at this time.
    • bank_name (Required when creating a subscription with ACH) The name of the bank where the customer’s account resides
    • bank_routing_number (Required when creating a subscription with ACH) The routing number of the bank
    • bank_account_number (Required when creating a subscription with ACH) The customer’s bank account number
    • bank_account_type When payment_type is bank_account, this defaults to checking and cannot be changed
    • bank_account_holder_type When payment_type is bank_account, this defaults to personal and cannot be changed
    • payment_method_nonce
    • paypal_email
    • vault_token (Only allowed during the creation of a new payment profile) If you have an existing vault_token from your gateway, you may associate it with this new payment profile.
    • current_vault (Required when you pass in a vault_token) One of bogus (for testing), authorizenet, trust_commerce, payment_express, beanstream, braintree1 (deprecated), braintree_blue, paypal (deprecated), quickpay, eway, eway_rapid (deprecated), eway_rapid_std, stripe, pin, wirecard, bpoint, firstdata, elavon, cybersource, paymill, litle, moneris, moneris_us, orbital, fusebox, authorizenet_cim, or chargify.

Methods

format may be either ‘xml’ or ‘json’.

Read

URL: https://<subdomain>.chargify.com/payment_profiles/<payment_profile_id>.<format>
Method: GET
Required Parameters: payment_profile_id
Response: A single Payment Profile

When the Payment Profile is a Credit Card

"payment_profile": {
  "billing_address": "123 Main St.",
  "billing_address_2": "Apt 5C",
  "billing_city": "Penn Yan",
  "billing_country": "US",
  "billing_state": "NY",
  "billing_zip": "12345",
  "card_type": "bogus",
  "current_vault": "bogus",
  "customer_id": 52435,
  "customer_vault_token": null,
  "expiration_month": 12,
  "expiration_year": 2022,
  "first_name": "Marianne",
  "id": 542,
  "last_name": "Heidenreich",
  "masked_card_number": "XXXX-XXXX-XXXX-1",
  "vault_token": "1",
  "payment_type": "credit_card"
}

When the Payment Profile is a Bank Account

"payment_profile": {
  "bank_account_holder_type": "personal",
  "bank_account_type": "checking",
  "bank_name": "Best Bank",
  "billing_address": "123 Main St.",
  "billing_address_2": "Apt 5C",
  "billing_city": "Penn Yan",
  "billing_country": "US",
  "billing_state": "NY",
  "billing_zip": "12345",
  "current_vault": "bogus",
  "customer_id": 7674,
  "customer_vault_token": null,
  "first_name": "Mark",
  "id": 543,
  "last_name": "Wahlberg",
  "masked_bank_account_number": "XXXXXXX1",
  "masked_bank_routing_number": "XXXXXXX1",
  "vault_token": "1",
  "payment_type": "bank_account"
}

Create

URL: https://<subdomain>.chargify.com/payment_profiles.<format>
Method: POST
Required Parameters: XML or JSON data, as specified by the required attributes
Response: The created payment profile (see output for “Read”)


  {
    "payment_profile": {
      "first_name": "Jessica",
      "last_name": "Test",
      "last_four" : 1111,
      "card_type": "visa",
      "expiration_month": 10,
      "expiration_year": 2018,
      "customer_id": 13733362,
      "current_vault": "bogus",
      "vault_token": "1",
      "billing_address": "123 Main St.",
      "billing_city": "Boston",
      "billing_state": "MA",
      "billing_zip": "02120",
      "billing_country": "US",
      "customer_vault_token": null,
      "billing_address_2": null,
      "payment_type": "credit_card"
    }
  }

Note

Creating a new payment profile for a customer via the API will not make that payment profile current for any of the customer’s subscriptions. To make a change, please use one of the following methods:

  • Change the default payment profile for the subscription.
  • Select the Subscription in the Admin UI and choose Payment Details, then click the ‘Make Active Payment Method’ link next to the desired payment profile.

Update

URL: https://<subdomain>.chargify.com/payment_profiles/<payment_profile_id>.<format>
Method: PUT
Required Parameters: XML or JSON data, as specified by the required attributes
Response: The updated payment profile (see output for “Read”)

Notes on updating payment profiles via the API

  • Merchants with Authorize.net or Stripe as their payment gateway can update their customer’s credit cards without passing in the full credit card number and CVV.
  • If you are using Authorize.net or Stripe, Chargify will ignore the credit card number and CVV when processing an update via the API, and attempt a partial update instead. If you wish to change the card number on a payment profile, you will need to create a new payment profile for the given customer.
  • A payment profile cannot be updated with the attributes of another type of payment profile. For example, if the payment profile you are attempting to update is a credit card, you cannot pass in bank account attributes (like bank_account_number), and vice versa.
  • If you are using Authorize.net or Stripe, you may elect to manually trigger a retry for a past due subscription after a partial update.

Delete

See Deleting a Payment Profile in the Subscriptions API documentation.