Payment sources

API Version

Product Catalog

Library

Updates

This API obsoletes the Cards API in Chargebee.

Represents the payment source for the customer. Specific types of payment source (Card, Direct Debit, Paypal Express Checkout, etc.) is defined as sub-resource in the response object. You can find the list of supported payment sources and the expected input parameters here. See Payment source attributes for a descriptive list of attributes and payment source types.

Sample payment source [ JSON ]

{
    "card": {
        "brand": "visa",
        "expiry_month": 5,
        "expiry_year": 2022,
        "first_name": "MyCard",
        "funding_type": "credit",
        "iin": "******",
        "last4": "4242",
        "last_name": "testing",
        "masked_number": "************4242",
        "object": "card"
    },
    "created_at": 1517487233,
    "customer_id": "__test__XpbTXGTSRp4QZ1EK",
    "deleted": false,
    "gateway": "stripe",
    "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
    "id": "pm___test__XpbTXGTSRp4R8ZEN",
    "issuing_country": "US",
    "object": "payment_source",
    "reference_id": "cus_J7rVykqiooX1ng/card_1IVbmWJv9j0DyntJS7Bzo5q5",
    "resource_version": 1517487233588,
    "status": "valid",
    "type": "card",
    "updated_at": 1517487233
}

id

string, max chars=40
Identifier of the payment source

resource_version

optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this payment source resource was last updated.

created_at

timestamp(UTC) in seconds
Timestamp indicating when this payment source resource is created.

customer_id

string, max chars=50
Identifier of the customer with whom this payment source is associated.

type

enumerated string
Type of payment source

Possible values are

reference_id

string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the 'billing agreement id'. For GoCardless direct debit this will be 'mandate id'. In the case of card payments this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one time temporary token provided by gateways like Stripe.

status

enumerated string, default=valid
Current status of the payment source.

Possible values are

gateway

enumerated string
Name of the gateway this payment source is stored with.

Possible values are

gateway_account_id

optional, string, max chars=50
The gateway account to which this payment source is stored with.

ip_address

optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.

issuing_country

optional, string, max chars=50
two-letter(alpha2) ISO country code.

deleted

boolean
Indicates that this resource has been deleted.

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this payment_source. This is always the same as the business entity of the customer.

card
Show attributes [+]

optional, card
Card details associated with this payment source.

Card attributes

first_name

optional, string, max chars=50
Cardholder's first name

last_name

optional, string, max chars=50
Cardholder's last name

iin

string, min chars=6, max chars=6
The Issuer Identification Number, i.e. the first six digits of the card number

last4

string, min chars=4, max chars=4
Last four digits of the card number

brand

enumerated string
Card brand

Possible values are

funding_type

enumerated string
Card Funding type

Possible values are

expiry_month

integer, min=1, max=12
Card expiry month.

expiry_year

integer
Card expiry year.

billing_addr1

optional, string, max chars=150
Address line 1, as available in card billing address.

billing_addr2

optional, string, max chars=150
Address line 2, as available in card billing address.

billing_city

optional, string, max chars=50
City, as available in card billing address.

billing_state_code

optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).

billing_state

optional, string, max chars=50
The state/province name.

billing_country

optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

billing_zip

optional, string, max chars=20
Postal or Zip code, as available in card billing address.

masked_number

optional, string, max chars=19
Masked credit card number that is safe to show.

bank_account
Show attributes [+]

optional, bank_account
Bank account details the direct debit or ACH or NetBanking agreement/mandate created with this payment source.

Bank account attributes

last4

string, min chars=4, max chars=4
Last four digits of the bank account number

name_on_account

optional, string, max chars=300
Account holder's name as per bank account.

first_name

optional, string, max chars=150
Account holder's first name as per bank account.

last_name

optional, string, max chars=150
Account holder's last name as per bank account.

direct_debit_scheme

optional, enumerated string
Bank account's scheme to which the mandate and associated payments are submitted.

Possible values are

bank_name

optional, string, max chars=100
Name of account holder's bank.

mandate_id

optional, string, min chars=1, max chars=50
Mandate Id. Applicable for SEPA, BACS, Autogiro, and BECS.

account_type

optional, enumerated string
Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay NetBanking users only. If not passed, account type is taken as null.

Possible values are

echeck_type

optional, enumerated string
For Authorize.net ACH users only. Indicates the type of eCheck.

Possible values are

account_holder_type

optional, enumerated string
For Stripe ACH users only. Indicates the account holder type.

Possible values are

email

optional, string, max chars=70
Account holder's email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.

boleto
Show attributes [+]

optional, cust_voucher_source
Boleto payment source details of the customer

billing_address
Show attributes [+]

optional, billing_address
Billing address for the payment source.

Billing address attributes

first_name

optional, string, max chars=150
The first name of the billing contact.

last_name

optional, string, max chars=150
The last name of the billing contact.

email

optional, string, max chars=70
The email address.

company

optional, string, max chars=250
The company name.

phone

optional, string, max chars=50
The phone number.

line1

optional, string, max chars=150
Address line 1

line2

optional, string, max chars=150
Address line 2

line3

optional, string, max chars=150
Address line 3

city

optional, string, max chars=50
The name of the city.

state_code

state

optional, string, max chars=50
State or Province

country

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

zip

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

validation_status

optional, enumerated string, default=not_validated
The address verification status.

Possible values are

amazon_payment
Show attributes [+]

optional, amazon_payment
Amazon payments details associated with this payment source.

upi
Show attributes [+]

optional, upi
Represents the payment method that allows you to make payments directly using a bank account.

paypal
Show attributes [+]

optional, paypal
PayPal Express Checkout details associated with this payment source.

venmo
Show attributes [+]

optional, venmo
Venmo details associated with this payment source.

klarna_pay_now
Show attributes [+]

optional, klarna_pay_now
Klarna Pay Now payment source details of the customer

mandates
Show attributes [+]

optional, list of mandate
Mandate details associated with the payment source.

id

string, max chars=40
Identifier of the payment source

resource_version

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this payment source resource was last updated.

created_at

timestamp(UTC) in seconds
Timestamp indicating when this payment source resource is created.

customer_id

string, max chars=50
Identifier of the customer with whom this payment source is associated.

type

enumerated string
Type of payment source

Possible values are

reference_id

status

enumerated string, default=valid
Current status of the payment source.

Possible values are

gateway

enumerated string
Name of the gateway this payment source is stored with.

Possible values are

gateway_account_id

optional, string, max chars=50
The gateway account to which this payment source is stored with.

ip_address

optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.

issuing_country

optional, string, max chars=50
two-letter(alpha2) ISO country code.

deleted

boolean
Indicates that this resource has been deleted.

business_entity_id

optional, string, max chars=50
The unique ID of the business entity of this payment_source. This is always the same as the business entity of the customer.

card

optional, card
Card details associated with this payment source.

bank_account

optional, bank_account
Bank account details the direct debit or ACH or NetBanking agreement/mandate created with this payment source.

boleto

optional, cust_voucher_source
Boleto payment source details of the customer

billing_address

optional, billing_address
Billing address for the payment source.

amazon_payment

optional, amazon_payment
Amazon payments details associated with this payment source.

upi

optional, upi
Represents the payment method that allows you to make payments directly using a bank account.

paypal

optional, paypal
PayPal Express Checkout details associated with this payment source.

venmo

optional, venmo
Venmo details associated with this payment source.

klarna_pay_now

optional, klarna_pay_now
Klarna Pay Now payment source details of the customer

mandates

optional, list of mandate
Mandate details associated with the payment source.

Try in API Explorer

This API offers an alternative way to create a payment source using a single-use gateway temporary token, which is generally provided by your payment gateway. In the case of Stripe, this temporary token is generated according to the instruction detailed in Stripe documentation.

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Mx02v" \
     -d customer_id="__test__XpbTXGTSRp4QZ1EK" \
     -d type="CARD" \
     -d tmp_token="tok_1IVbmWJv9j0DyntJuLTiAhzK"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487231,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4QZ1EK",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
            "object": "payment_method",
            "reference_id": "cus_J7rVykqiooX1ng/card_1IVbmWJv9j0DyntJS7Bzo5q5",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4R8ZEN",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487233590,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487233
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 5,
            "expiry_year": 2022,
            "first_name": "MyCard",
            "funding_type": "credit",
            "iin": "******",
            "last4": "4242",
            "last_name": "testing",
            "masked_number": "************4242",
            "object": "card"
        },
        "created_at": 1517487233,
        "customer_id": "__test__XpbTXGTSRp4QZ1EK",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4R8ZEN",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVykqiooX1ng/card_1IVbmWJv9j0DyntJS7Bzo5q5",
        "resource_version": 1517487233588,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487233
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

gateway_account_id[]

optional, string, max chars=50
The gateway account to which the payment source is associated.

type[]

required, enumerated string
Type of payment source.

Possible values are

tmp_token[]

required, string, max chars=65k
Single-use token created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.

issuing_country[]

optional, string, max chars=50
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.

replace_primary_payment_source[]

optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.

additional_information[]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user's payment method may not be the same as their country of residence. Hence the user's country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user's identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
bank_of_america: While passing raw card details to Bank of America, your user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part.
- merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.
ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- payer: User related information.
  - document: Document is the user's identification number based on their country.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

This API provides an alternative way to create a payment source using a permanent token, instead of having to add the full payment method details via API or the Chargebee UI. Permanent tokens are provided by payment gateways such as Stripe.

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Q5TE9" \
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Mx02v" \
     -d reference_id="cus_J7rVCB7oVNyDJF" \
     -d type="CARD"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487229,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4Q5TE9",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
            "object": "payment_method",
            "reference_id": "cus_J7rVCB7oVNyDJF/card_1IVbmUJv9j0DyntJninpvymH",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4QTuEF",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487231068,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487231
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "credit",
            "iin": "******",
            "last4": "1111",
            "masked_number": "************1111",
            "object": "card"
        },
        "created_at": 1517487231,
        "customer_id": "__test__XpbTXGTSRp4Q5TE9",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4QTuEF",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVCB7oVNyDJF/card_1IVbmUJv9j0DyntJninpvymH",
        "resource_version": 1517487231066,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487231
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

type[]

required, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.

Possible values are

gateway_account_id[]

optional, string, max chars=50
The gateway account to which the payment source is associated.

reference_id[]

optional, string, max chars=200

The reference id. In the case of Amazon and PayPal, this will be the billing agreement ID. For GoCardless direct debit this will be mandate_id. In the case of a card, this will be the identifier provided by the gateway or card vault for the specific payment method resource.

Note:

This is not the one-time temporary token provided by gateways like Stripe.
reference_id is an alternative for payment_method_token, customer_profile_token, network_transaction_id, or mandate_id.
payment_method_token, customer_profile_token, network_transaction_id, or mandate_id cannot be used with reference_id.
reference_id is a combination of multiple tokens available at the gateway. Learn more about the combination of each gateway from this document.

issuing_country[]

optional, string, max chars=50
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.

replace_primary_payment_source[]

payment_method_token[]

optional, string, max chars=100

An identifier provided by the gateway or card vault for the specific payment method resource.

Note:

payment_method_token is an alternative for reference_id and cannot be used with reference_id.

customer_profile_token[]

optional, string, max chars=100

A unique identifier associated with a customer`s profile within a payment gateway.

Note:

customer_profile_token is an alternative for reference_id and cannot be used with reference_id.

network_transaction_id[]

optional, string, max chars=100

An identifier of the payment or authorization transaction at the gateway initiated using this payment method.

Note:

network_transaction_id is an alternative for reference_id and cannot be used with reference_id.

mandate_id[]

optional, string, max chars=100

An identifier of mandates which is an authorization given by the payer (usually a customer or account holder) to allow a third party such as a merchant or service provider to initiate payments from their account.

Note:

mandate_id is an alternative for reference_id and cannot be used with reference_id.

skip_retrieval[]

optional, boolean, default=false

By default, the value is false and payment method details will be retrieved from the selected payment gateway using reference_id or payment_method_token / customer_profile_token / network_transaction_id / mandate_id. Learn more about the multiple token combinations of each gateway from this document.

Enter the value as true for the payment gateways that do not allow to retrieve the payment method details. Once passed, it will create payment method at Chargebee with the provided attributes in payment_method_token, customer_profile_token, network_transaction_id, mandate_id, card, and billing_address.

Note:

Currently, the skip_retrieval value as true is only supported for the Vantiv payment gateway.

additional_information[]

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user's payment method may not be the same as their country of residence. Hence the user's country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user's identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
bank_of_america: While passing raw card details to Bank of America, your user's device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part.
- merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.
ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- payer: User related information.
  - document: Document is the user's identification number based on their country.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device

card

Parameters for card
pass parameters as card[<param name>]

card[last4]

optional, string, min chars=4, max chars=4

card[iin]

optional, string, min chars=6, max chars=6

card[expiry_month]

optional, integer, min=1, max=12

card[expiry_year]

optional, integer

card[brand]

optional, enumerated string

Possible values are

card[funding_type]

optional, enumerated string

Possible values are

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

billing_address[first_name]

optional, string, max chars=150

billing_address[last_name]

optional, string, max chars=150

billing_address[email]

optional, string, max chars=70

billing_address[line1]

optional, string, max chars=150

billing_address[line2]

optional, string, max chars=150

billing_address[line3]

optional, string, max chars=150

billing_address[city]

optional, string, max chars=50

billing_address[state_code]

optional, string, max chars=50

billing_address[state]

optional, string, max chars=50

billing_address[zip]

optional, string, max chars=20

billing_address[country]

optional, string, max chars=50

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_token \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4REKES" \
     -d token_id="cb_tok___test__XpbTXGTSRp4RaBEV"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487233,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4REKES",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
            "object": "payment_method",
            "reference_id": "cus_J7rVlNvtSznu6p/card_1IVbmYJv9j0DyntJOIWtQCkk",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4RqgEX",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487236333,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487236
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 5,
            "expiry_year": 2022,
            "first_name": "MyCard",
            "funding_type": "credit",
            "iin": "******",
            "last4": "4242",
            "last_name": "testing",
            "masked_number": "************4242",
            "object": "card"
        },
        "created_at": 1517487236,
        "customer_id": "__test__XpbTXGTSRp4REKES",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4RqgEX",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVlNvtSznu6p/card_1IVbmYJv9j0DyntJOIWtQCkk",
        "resource_version": 1517487236331,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487236
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_token

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

replace_primary_payment_source[]

token_id[]

required, string, max chars=40
Token generated by Chargebee JS representing payment method details.

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Used to attach the card to the customer after 3DS completion. Learn more on the 3DS implementation via Chargebee APIs.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_payment_intent \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4MunE0" \
     -d "payment_intent[gateway_account_id]"="gw___test__5SK2lMpwSRp4Mx02v" \
     -d "payment_intent[gw_token]"="pi_1IVbmIJv9j0DyntJo1AUvK4o"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487217,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4MunE0",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
            "object": "payment_method",
            "reference_id": "cus_J7rVjoqwlD18Ei/pm_1IVbmIJv9j0DyntJCh6glSQB",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4Q00E4",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487229215,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487229
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 7,
            "expiry_year": 2050,
            "funding_type": "credit",
            "iin": "******",
            "last4": "3055",
            "masked_number": "************3055",
            "object": "card"
        },
        "created_at": 1517487229,
        "customer_id": "__test__XpbTXGTSRp4MunE0",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4Q00E4",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVjoqwlD18Ei/pm_1IVbmIJv9j0DyntJCh6glSQB",
        "resource_version": 1517487229213,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487229
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_payment_intent

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

replace_primary_payment_source[]

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

optional, string, max chars=150

payment_intent[gateway_account_id]

optional, string, max chars=50

payment_intent[gw_token]

optional, string, max chars=65k

payment_intent[payment_method_type]

optional, enumerated string

Possible values are

payment_intent[reference_id]

optional, string, max chars=65k

payment_intent[additional_info]

optional, jsonobject

payment_intent[additional_information]

optional, jsonobject

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Create a voucher payment method for the payment source.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_voucher_payment_source \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d "voucher_payment_source[voucher_type]"="BOLETO" \
     -d "voucher_payment_source[tax_id]"="00000000000000" \
     -d "voucher_payment_source[gateway_account_id]"="gw_161my9TXG5oNYwgv" \
     -d "voucher_payment_source[billing_address]"='{"first_name":"John","last_name":"Doe","line1":"No 4 metro street","line2":"rio","country_code":"br","state_code":"ap","city":"rio","postal_code":"20080003","email":"johndoe@example.com"}'

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "payment_source": {
        "id": "pm_HmhZXuiTcB6bEh1K9s",
        "updated_at": 1682183992,
        "resource_version": 1682183992360,
        "deleted": false,
        "object": "payment_source",
        "customer_id": "__test__XpbTXGTSRp4Mg0Dr",
        "type": "boleto",
        "reference_id": "cus_NlGdeYYqRj9ca9/pm_1Mzk6GK7ilSfRo7vhZxk82n8",
        "status": "valid",
        "gateway": "stripe",
        "gateway_account_id": "gw_161my9TXG5oNYwgv",
        "created_at": 1682183992,
        "boleto": {
            "last4": "0000",
            "first_name": "John",
            "last_name": "Doe",
            "email": "johndoe@example.com",
            "object": "cust_voucher_source"
        },
        "billing_address": {
            "line1": "No 4 metro street",
            "line2": "rio street",
            "city": "rio",
            "state_code": "ap",
            "validation_status": "not_validated",
            "object": "billing_address"
        },
        "business_entity_id": "org1"
    },
    "customer": {
        "id": "__test__XpbTXGTSRp4Mg0Dr",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe2@example.com",
        "auto_collection": "off",
        "offline_payment_method": "no_preference",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1682180803,
        "taxability": "taxable",
        "updated_at": 1682183992,
        "pii_cleared": "active",
        "channel": "web",
        "resource_version": 1682183992357,
        "deleted": false,
        "object": "customer",
        "card_status": "no_card",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "unbilled_charges": 0,
        "preferred_currency_code": "BRL",
        "business_entity_id": "org1"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_voucher_payment_source

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

voucher_payment_source

Parameters for voucher_payment_source
pass parameters as voucher_payment_source[<param name>]

voucher_payment_source[voucher_type]

required, enumerated string

Possible values are

voucher_payment_source[gateway_account_id]

optional, string, max chars=50

voucher_payment_source[tax_id]

optional, string, max chars=20

voucher_payment_source[billing_address]

optional, jsonobject

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_card \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d "card[number]"="378282246310005" \
     -d "card[cvv]"="100" \
     -d "card[expiry_year]"=2022 \
     -d "card[expiry_month]"=12

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487216,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4Mg0Dr",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4LJJ1y",
            "object": "payment_method",
            "reference_id": "tok___test__XpbTXGTSRp4MkpDu",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4Ml3Dv",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487216760,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487216
    },
    "payment_source": {
        "card": {
            "brand": "american_express",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "iin": "378282",
            "last4": "0005",
            "masked_number": "***********0005",
            "object": "card"
        },
        "created_at": 1517487216,
        "customer_id": "__test__XpbTXGTSRp4Mg0Dr",
        "deleted": false,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4LJJ1y",
        "id": "pm___test__XpbTXGTSRp4Ml3Dv",
        "object": "payment_source",
        "reference_id": "tok___test__XpbTXGTSRp4MkpDu",
        "resource_version": 1517487216756,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487216
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_card

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

replace_primary_payment_source[]

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

optional, string, max chars=50

card[first_name]

optional, string, max chars=50

card[last_name]

optional, string, max chars=50

card[number]

required, string, max chars=1500

card[expiry_month]

required, integer, min=1, max=12

card[expiry_year]

required, integer

card[cvv]

optional, string, max chars=520

card[preferred_scheme]

optional, enumerated string

Possible values are

card[billing_addr1]

optional, string, max chars=150

card[billing_addr2]

optional, string, max chars=150

card[billing_city]

optional, string, max chars=50

card[billing_state_code]

optional, string, max chars=50

card[billing_state]

optional, string, max chars=50

card[billing_zip]

optional, string, max chars=20

card[billing_country]

optional, string, max chars=50

card[additional_information]

optional, jsonobject

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

This API adds a Direct Debit payment source for a customer. The bank account details collected from your customer are passed as input to this API.

Automated Clearing House (ACH) Network

ACH is an electronic network for passing financial transactions in the US. Chargebee currently supports ACH via Stripe , Authorize.Net, and GoCardless.

Note:

For ACH via Stripe, it is mandatory to pass user details such as IP address(chargebee-request-origin-ip) and the device information(chargebee-request-origin-device).

Bank account verification

Once the bank account has been added, it needs to be verified.

For Stripe, perform this verification using the Verify bank account payment source API.
For Authorize.net, the verification is done by them in 2-3 days after the account is added. No intervention is needed from your side or your customer.

Single Euro Payment Area (SEPA)

SEPA is an initiative that integrates bank transfer payments denominated in euro. It is supported via GoCardless, Stripe and Adyen.

Note:

For SEPA via Stripe, it is mandatory to pass user details such as IP address and device information.
For GoCardless, local bank details can be passed instead of IBAN.

Bacs Payment Schemes Limited (BACS) and Bg Autogiro

Bacs is an organization that manages the Direct Debit and Direct Credit payment methods in the UK. Bg Autogiro is a Direct Debit scheme for krona denominated payments in Sweden. Both Bacs and Bg Autogiro are supported via GoCardless.

Note:

For BACS via Stripe, it is mandatory to pass user details such as IP address(chargebee-request-origin-ip) and the device information(chargebee-request-origin-device).

Bulk Electronic Clearing System (BECS) and Pre-Authorized Debit (PAD)

BECS is an automated payment method for Direct Debit in Australia and New Zealand while PAD does the same for Canada. GoCardless supports both.

For Direct Debit, the customer needs to accept a mandate that allows the merchant to debit their bank account. This agreement PDF can be obtained using the Retrieve direct debit agreement PDF API.

If the customer has already reached the payment source limit allowed for the site, pass replace_primary_payment_source as true. Alternatively, delete one of the payment sources first and then add the bank account payment source for the customer.

Note:

For BECS via Stripe, it is mandatory to pass user details such as IP address(chargebee-request-origin-ip) and the device information(chargebee-request-origin-device).

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/create_bank_account \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Ly9Dj" \
     -d "bank_account[gateway_account_id]"="gw___test__5SK2lMpwSRp4Ljs2t" \
     -d "bank_account[account_number]"="000222222227" \
     -d "bank_account[routing_number]"="110000000" \
     -d "bank_account[bank_name]"="US Bank" \
     -d "bank_account[account_holder_type]"="INDIVIDUAL" \
     -d "bank_account[account_type]"="SAVINGS" \
     -d "bank_account[first_name]"="Shay" \
     -d "bank_account[last_name]"="Liam"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": true,
        "auto_collection": "on",
        "created_at": 1517487213,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4Ly9Dj",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Ljs2t",
            "object": "payment_method",
            "reference_id": "cus_J7rVKldNI2hKt0/ba_1IVbmEJv9j0DyntJTe5oRPZE",
            "status": "pending_verification",
            "type": "direct_debit"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4MS7Dm",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487215586,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487215
    },
    "payment_source": {
        "bank_account": {
            "account_holder_type": "individual",
            "account_type": "not_applicable",
            "bank_name": "US Bank",
            "last4": "2227",
            "name_on_account": "Shay Liam",
            "object": "bank_account"
        },
        "created_at": 1517487215,
        "customer_id": "__test__XpbTXGTSRp4Ly9Dj",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Ljs2t",
        "id": "pm___test__XpbTXGTSRp4MS7Dm",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVKldNI2hKt0/ba_1IVbmEJv9j0DyntJTe5oRPZE",
        "resource_version": 1517487215582,
        "status": "pending_verification",
        "type": "direct_debit",
        "updated_at": 1517487215
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_bank_account

customer_id[]

required, string, max chars=50
Identifier of the customer with whom this payment source is associated.

issuing_country[]

optional, string, max chars=50
2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.

replace_primary_payment_source[]

bank_account

Parameters for bank_account
pass parameters as bank_account[<param name>]

bank_account[gateway_account_id]

optional, string, max chars=50

bank_account[iban]

optional, string, min chars=10, max chars=50

bank_account[first_name]

optional, string, max chars=150

bank_account[last_name]

optional, string, max chars=150

bank_account[company]

optional, string, max chars=250

bank_account[email]

optional, string, max chars=70

bank_account[phone]

optional, string, max chars=50

bank_account[bank_name]

optional, string, max chars=100

bank_account[account_number]

optional, string, min chars=4, max chars=17

bank_account[routing_number]

optional, string, min chars=3, max chars=9

bank_account[bank_code]

optional, string, max chars=20

bank_account[account_type]

optional, enumerated string

Possible values are

bank_account[account_holder_type]

optional, enumerated string

Possible values are

bank_account[echeck_type]

optional, enumerated string

Possible values are

bank_account[swedish_identity_number]

optional, string, min chars=10, max chars=12

bank_account[billing_address]

optional, jsonobject

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Merchants look to update card details when:

The billing address of a customer has changed. In such a case, modify the billing address in the Chargebee and the payment gateway.
The expiration date of the card has been extended by the bank. (This usually happens when the date of card expiry is in near future).

Multiple parameters such as address, expiry date, month, and so on, can be updated through this API.

Meta data can also be added additionally(supported in Stripe only). Metadata is a JSON object. It is used to store additional information about customers.

In Stripe and Braintree payment gateways, changes in card details are auto-updated. This feature can also be used for other payment gateways in which auto-update is not enabled or is not supported by Chargebee.

Note : This endpoint supports Chargebee Test Gateway, Stripe , Braintree , Authorize.net , Worldpay US eCom , and WorldPay Direct Integration . For all other gateways, your customers must re-enter the full card details to update existing card details. For example, consider a customer not using the gateways mentioned above and wants to update the card[billing_addr1] parameter. In such a case, the customer must re-enter the value of all the parameters present in the card object.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4Xy9FR/update_card \
     -u {site_api_key}:\
     -d "card[first_name]"="John" \
     -d "card[last_name]"="Doe" \
     -d "card[expiry_month]"=5 \
     -d "card[expiry_year]"=2022 \
     -d "card[billing_addr1]"="#678 Mission Street" \
     -d "card[billing_city]"="New York City" \
     -d "card[billing_zip]"="10002" \
     -d "card[billing_state_code]"="NY" \
     -d "card[billing_country]"="US"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487258,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4Xi1FQ",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
            "object": "payment_method",
            "reference_id": "cus_J7rVemdQKHVECd/card_1IVbmxJv9j0DyntJlQ8osjf2",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4Xy9FR",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487261178,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487261
    },
    "payment_source": {
        "card": {
            "billing_addr1": "#678 Mission Street",
            "billing_city": "New York City",
            "billing_country": "US",
            "billing_zip": "10002",
            "brand": "visa",
            "expiry_month": 5,
            "expiry_year": 2022,
            "first_name": "John",
            "funding_type": "credit",
            "iin": "******",
            "last4": "1111",
            "last_name": "Doe",
            "masked_number": "************1111",
            "object": "card"
        },
        "created_at": 1517487259,
        "customer_id": "__test__XpbTXGTSRp4Xi1FQ",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4Xy9FR",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVemdQKHVECd/card_1IVbmxJv9j0DyntJlQ8osjf2",
        "resource_version": 1517487261179,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487261
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/update_card

gateway_meta_data[]

optional, jsonobject
Additional data about this resource can be passed to Stripe gateway here in the JSON Format. This will be stored along with payment source at the gateway account.

reference_transaction[]

optional, string, max chars=50
Reference transaction is used for future purchases. This is only applicable for Vantiv.

card

Parameters for card
pass parameters as card[<param name>]

card[first_name]

optional, string, max chars=50

card[last_name]

optional, string, max chars=50

card[expiry_month]

optional, integer, min=1, max=12

card[expiry_year]

optional, integer

card[billing_addr1]

optional, string, max chars=150

card[billing_addr2]

optional, string, max chars=150

card[billing_city]

optional, string, max chars=50

card[billing_zip]

optional, string, max chars=20

card[billing_state_code]

optional, string, max chars=50

card[billing_state]

optional, string, max chars=50

card[billing_country]

optional, string, max chars=50

card[additional_information]

optional, jsonobject

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

This API is used to update the payment source details of a customer. Information related to bank account payment source such as email, first name, and last name can be updated.

For GoCardless, Chargebee supports (ACH,BACS,SEPA,AUTOGIRO,BECS,BECS_NZ,PAD).
For Stripe, Chargebee only supports SEPA.

The API is only supported for the payment_method of type direct_debit.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__KyVnPbSerKGB5d/update_bank_account \
     -u {site_api_key}:\
     -d "bank_account[email]"="johndoe@example.com" \
     -d "bank_account[first_name]"="John" \
     -d "bank_account[last_name]"="Doe"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": true,
        "auto_collection": "on",
        "channel": "web",
        "created_at": 1517507082,
        "deleted": false,
        "email": "markhenry@example.com",
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__KyVnPbSerKFjFY",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "gateway_account_id": "gw___test__KyVnGoSerKFdA2t",
            "object": "payment_method",
            "reference_id": "cus_Jxe0kGs9uZuKX3/src_1JJiiNJv9j0DyntJXYkqBHE8",
            "status": "valid",
            "type": "direct_debit"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "EUR",
        "primary_payment_source_id": "pm___test__KyVnPbSerKGB5d",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517507084711,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517507084
    },
    "payment_source": {
        "bank_account": {
            "email": "johndoe@example.com",
            "last4": "3000",
            "mandate_id": "OI1M52OFAXGFQZRR",
            "name_on_account": "John Doe",
            "object": "bank_account"
        },
        "created_at": 1517507084,
        "customer_id": "__test__KyVnPbSerKFjFY",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVnGoSerKFdA2t",
        "id": "pm___test__KyVnPbSerKGB5d",
        "issuing_country": "DE",
        "object": "payment_source",
        "reference_id": "cus_Jxe0kGs9uZuKX3/src_1JJiiNJv9j0DyntJXYkqBHE8",
        "resource_version": 1517507084712,
        "status": "valid",
        "type": "direct_debit",
        "updated_at": 1517507084
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/update_bank_account

bank_account

Parameters for bank_account
pass parameters as bank_account[<param name>]

bank_account[first_name]

optional, string, max chars=150

bank_account[last_name]

optional, string, max chars=150

bank_account[email]

optional, string, max chars=70

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

This API can be used to verify bank accounts which have been added as payment source. This is applicable for Stripe ACH with micro-deposit mode bank accounts only. Stripe handles verification in two ways - via Plaid, and micro-deposit.

For verifying bank accounts via micro-deposit, Stripe deposits two small amounts to the bank account being added. These deposits will take 1-2 business days to appear on the customer's bank statement. The bank statement description for the two micro-deposits contains the amount and the values deposited. Your customer will need to relay the value of the two deposits to you, after which you can verify the bank account. Once the bank account has been verified, the payment source will be marked as "Valid".

A maximum of 10 failed verification attempts are allowed. Once this limit has been crossed, the bank account can no longer be verified, and will be marked as "Invalid" in Chargebee.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4YjRFc/verify_bank_account \
     -u {site_api_key}:\
     -d amount1=32 \
     -d amount2=45

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "payment_source": {
        "bank_account": {
            "account_holder_type": "individual",
            "account_type": "not_applicable",
            "bank_name": "US Bank",
            "last4": "2227",
            "name_on_account": "Shay Liam",
            "object": "bank_account"
        },
        "created_at": 1517487262,
        "customer_id": "__test__XpbTXGTSRp4YNIFZ",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Ljs2t",
        "id": "pm___test__XpbTXGTSRp4YjRFc",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rW1Bl7xQoLOW/ba_1IVbmzJv9j0DyntJXpjNOH1r",
        "resource_version": 1517487263313,
        "status": "valid",
        "type": "direct_debit",
        "updated_at": 1517487263
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/verify_bank_account

amount1[]

required, in cents, min=0
Value of the micro-deposits sent to the bank account.

amount2[]

required, in cents, min=0
Value of the micro-deposits sent to the bank account.

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Retrieves the payment source identified by the unique identifier.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__KyVmmpTSneqVht \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 12,
            "expiry_year": 2030,
            "funding_type": "credit",
            "iin": "411111",
            "last4": "1111",
            "masked_number": "************1111",
            "object": "card"
        },
        "created_at": 1517467526,
        "customer_id": "__test__KyVmmpTSneqFXs",
        "deleted": false,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__KyVmsTTSnefon30",
        "id": "pm___test__KyVmmpTSneqVht",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_NA13opXonQckcW/card_0MPh10J7ubj1SVcrJTe4m32g",
        "resource_version": 1517467526693,
        "status": "valid",
        "type": "card",
        "updated_at": 1517467526
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Lists all the payment sources

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode "type[is]"="card"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "payment_source": {
                "card": {
                    "brand": "visa",
                    "expiry_month": 12,
                    "expiry_year": 2022,
                    "first_name": "Richard",
                    "funding_type": "not_known",
                    "iin": "411111",
                    "last4": "1111",
                    "last_name": "Fox",
                    "masked_number": "************1111",
                    "object": "card"
                },
                "created_at": 1517487242,
                "customer_id": "__test__XpbTXGTSRp4SZ5En",
                "deleted": false,
                "gateway": "pin",
                "gateway_account_id": "gw___test__5SK2lMpwSRp4Sb831",
                "id": "pm___test__XpbTXGTSRp4TUQEq",
                "object": "payment_source",
                "reference_id": "LHqS22OIh4y61Af9CXHicQFCfuD",
                "resource_version": 1517487242630,
                "status": "valid",
                "type": "card",
                "updated_at": 1517487242
            }
        },
        {..}
    ],
    "next_offset": "[\"1517487233000\",\"209000000107\"]"
}

URL Format GET

https://{site}.chargebee.com/api/v2/payment_sources

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set 'offset' to the value of 'next_offset' obtained in the previous iteration of the API call.

subscription_id[]

optional, string, max chars=50
Unique subscription identifier that helps to retrieve the payment source of a subscription which has mandate associated to it.

include_deleted[]

optional, boolean, default=false
Indicates whether to include deleted objects in the list. The deleted objects have the attribute 'deleted' as 'true'.

sort_by[<sort-order>]

optional, string filter
Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

customer_id[<operator>]

optional, string filter
To filter based on Customer Id.
Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "3bdjnDnsdQn"

type[<operator>]

optional, enumerated string filter
Type of payment source. Possible values are : card, paypal_express_checkout, amazon_payments, direct_debit, generic, alipay, unionpay, apple_pay, wechat_pay, ideal, google_pay, sofort, bancontact, giropay, dotpay, upi, netbanking_emandates, venmo, pay_to, faster_payments, sepa_instant_transfer, automated_bank_transfer, klarna_pay_now, online_banking_poland, payconiq_by_bancontact
Supported operators : is, is_not, in, not_in

Example → type[is] = "card"

status[<operator>]

optional, enumerated string filter
Current status of the payment source. Possible values are : valid, expiring, expired, invalid, pending_verification
Supported operators : is, is_not, in, not_in

Example → status[is] = "valid"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter
Timestamp indicating when this payment source resource was last updated.
Supported operators : after, before, on, between

Example → updated_at[after] = "1435054328"

created_at[<operator>]

optional, timestamp(UTC) in seconds filter
Timestamp indicating when this payment source resource is created.
Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"

payment_source

always returned
Resource object representing payment_source

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Try in API Explorer

Switches the gateway in which this payment source information is stored.

This is applicable only if the payment source is present in Spreedly vault.

This operation does not support switching between Braintree and Stripe. If you need help using this API, contact support@chargebee.com.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4XbjFJ/switch_gateway_account \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Wrl37"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487256,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4X57FI",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "payment_method": {
            "gateway": "pin",
            "gateway_account_id": "gw___test__5SK2lMpwSRp4Wrl37",
            "object": "payment_method",
            "reference_id": "UKZpy3LgND7f5jOIeAjwXbRsbEx",
            "status": "valid",
            "type": "card"
        },
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm___test__XpbTXGTSRp4XbjFJ",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487258458,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487258
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "not_known",
            "iin": "411111",
            "last4": "1111",
            "masked_number": "************1111",
            "object": "card"
        },
        "created_at": 1517487258,
        "customer_id": "__test__XpbTXGTSRp4X57FI",
        "deleted": false,
        "gateway": "pin",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Wrl37",
        "id": "pm___test__XpbTXGTSRp4XbjFJ",
        "object": "payment_source",
        "reference_id": "UKZpy3LgND7f5jOIeAjwXbRsbEx",
        "resource_version": 1517487258565,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487258
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/switch_gateway_account

gateway_account_id[]

required, string, max chars=50
The gateway account you want to switch to.

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Copies this payment source information to the gateway specified in the API.

This is useful if you want to port your customer's card details into another gateway.

This operation does not support copying of cards from Stripe and Braintree gateways. If you need help using this API, contact support@chargebee.com.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4TUQEq/export_payment_source \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4SXM2z"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "third_party_payment_method": {
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4SXM2z",
        "object": "third_party_payment_method",
        "reference_id": "cus_J7rVdlHN2uZpSx/card_1IVbmjJv9j0DyntJPYARLiEw",
        "type": "card"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/export_payment_source

gateway_account_id[]

required, string, max chars=50
The gateway account you want to copy the card.

third_party_payment_method

always returned
Resource object representing third_party_payment_method

Try in API Explorer

Deletes a payment source. Once the payment source is deleted, if

Deleted payment source is Primary, and Backup is available
- The Backup payment source will become the Primary payment source.
Deleted payment source is Primary, and no Backup is available
- The other payment source available, but not assigned to any subscription, will become the Primary payment source.
  
  Note: When multiple payment sources exist, the payment method added most recently will be considered.
- If other payment sources available are assigned to subscriptions, the auto collection attribute for the customer will be set to Off, and the events card_deleted and payment_source_deleted will be triggered.
Deleted payment source is attached to subscriptions
- Dunning will be initiated for subscriptions attached to this payment source if auto collection is set to On, and when no customer default is present.

If there is no such payment source present in the gateway for the customer, this API will return successfully without throwing any error.

Note :

If you delete the only available payment method of a customer in Chargebee, it also deletes the customer's record at the gateway. To delete the payment method locally(delete only in Chargebee), use Local Delete a Payment Source API .

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4SEvEe/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517487236,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4Rx1Ed",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487238746,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487238
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "credit",
            "iin": "411111",
            "last4": "1111",
            "masked_number": "************1111",
            "object": "card"
        },
        "created_at": 1517487237,
        "customer_id": "__test__XpbTXGTSRp4Rx1Ed",
        "deleted": true,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4SEvEe",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVgQok1LkbJ9/card_1IVbmbJv9j0DyntJhbTqsfn1",
        "resource_version": 1517487237828,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487237
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/delete

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Try in API Explorer

Delete a payment source reference from a Chargebee customer without deleting or altering payment source data stored at the payment gateway.

Impacts

Payment Source

Sets deleted = true on the specified payment_source and detaches it from the customer. The payment source is no longer accessible through the API or the UI.

Customer

If the deleted payment_source is the customer's only payment method and auto_collection is on, automatic payment collection for future invoices fails.

If the deleted payment source was the primary payment method for the customer, and a backup exists, Chargebee promotes the backup to primary.

If no backup is set but other payment_source objects exist for the customer, Chargebee promotes one of them to primary.

Subscription

When you delete a payment source linked to an active subscription, Chargebee immediately clears the payment_source_id on that subscription. Future charges use the customer's primary_payment_source_id.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4V0hEw/delete_local \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517487247,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp4UhfEv",
        "last_name": "Henry",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517487248592,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517487248
    },
    "payment_source": {
        "card": {
            "brand": "visa",
            "expiry_month": 12,
            "expiry_year": 2022,
            "funding_type": "credit",
            "iin": "411111",
            "last4": "1111",
            "masked_number": "************1111",
            "object": "card"
        },
        "created_at": 1517487248,
        "customer_id": "__test__XpbTXGTSRp4UhfEv",
        "deleted": true,
        "gateway": "stripe",
        "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v",
        "id": "pm___test__XpbTXGTSRp4V0hEw",
        "issuing_country": "US",
        "object": "payment_source",
        "reference_id": "cus_J7rVsWKqWFpyBS/card_1IVbmmJv9j0DyntJVAKlFn5a",
        "resource_version": 1517487248475,
        "status": "valid",
        "type": "card",
        "updated_at": 1517487248
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust-payment-source-id}/delete_local

customer

always returned
Resource object representing customer

payment_source

always returned
Resource object representing payment_source

Sample payment source [ JSON ]

API Index URL

Model Class

Payment source attributes

Consent Fields for Payment source

Custom Fields for Payment source

Create using gateway temporary token ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create using permanent token ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create using Chargebee token ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create using payment intent ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create a voucher payment method ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create a card payment source ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create a bank account payment source ¶

Automated Clearing House (ACH) Network

Bank account verification

Single Euro Payment Area (SEPA)

Bacs Payment Schemes Limited (BACS) and Bg Autogiro

Bulk Electronic Clearing System (BECS) and Pre-Authorized Debit (PAD)

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a card payment source ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters