Core Resources

Payment methods

The Payment Method object holds payment and billing information. A Customer may be associated with many Payment Methods, and an Addresses record must be associated with at least one Payment_method.

Important - If you see the following error when accessing Payment Methods endpoints: "You do not have sufficient permissions (scopes) for this object", the token you are using has not been configured with correct access permissions. Update the token to have "Read access" or "Read and Write access" depending on your use case.

29 additions in V2, marked New

Everything marked New also works when you send X-Recharge-Version: 2021-11.

Endpoints

POST/payment_methods
GET/payment_methods/{id}
PUT/payment_methods/{id}
DELETE/payment_methods/{id}
GET/payment_methods

#The payment method object

The Payment Method object holds payment and billing information. A Customer may be associated with many payment methods, and an Addresses record must be associated with at least one Payment Method.

Attributes

idinteger
The unique payment method id for a customer.
customer_idinteger
The Recharge customer_id.
includeobjectNew
An object containing the related resources requested with the include query parameter. Returned as an empty object when no related resources are requested.
Show child attributesHide child attributes22 new
- addressesarrayNew
  The Addresses that use this payment method.
  Only returned when include=addresses is passed.
- customerobjectNew
  The Customer the payment method belongs to.
  Only returned when include=customer is passed.
deleted_atdatetime · nullableNew
The date and time when the payment method was deleted. null for payment methods that have not been deleted.
Only returned by the list endpoint when include_deleted=true is passed.
created_atdatetime
The date and time when the payment method was created.
defaultboolean
true if this is default payment method for the Customer.
To update the Payment Method that will be used for processing charges for a specific Address, use Update an address method with a payment_method_id.
payment_detailsobject
Details about the specific payment method. The keys returned depend on payment_type: CREDIT_CARD and AMAZON_PAY return brand, last4, exp_month and exp_year (plus wallet_type and funding_type when available); APPLE_PAY and GOOGLE_PAY return brand, last4, exp_month and exp_year; SEPA_DEBIT returns bank_code, country, external_mandate_id and last4; PAYPAL returns paypal_email and paypal_payer_id.
Those details will vary based on the payment_type
Show child attributesHide child attributes113 new
- bank_codestring · nullableNew
  The bank code of the account.
  Only returned when payment_type is SEPA_DEBIT.
- brandstring
  Payment_method brand or company powering it.
  valid for CREDIT_CARD only.
- countrystring · nullableNew
  The country of the bank account.
  Only returned when payment_type is SEPA_DEBIT.
- exp_monthinteger
  Payment_method expiry month.
  valid for CREDIT_CARD only.
- exp_yearinteger
  Payment_method expiry year.
  valid for CREDIT_CARD only.
- external_mandate_idstring · nullableNew
  The ID of the debit mandate at the processor.
  Only returned when payment_type is SEPA_DEBIT.
- last4string
  last 4-digits of the identifier.
  valid for CREDIT_CARD only.
- paypal_emailstring
  email linked to .
  valid for PAYPAL only.
- paypal_payer_idstring
  paypal user identifier.
  valid for PAYPAL only.
- wallet_typestring
  If a digital wallet.
- funding_typestring
  Type of funding for the Payment Method.
payment_typestring
The type of payment this is.
Possible values
CREDIT_CARDPAYPALAPPLE_PAYGOOGLE_PAYSEPA_DEBITIDEALSHOP_PAYPAYPAL_EXPRESSSOFORTGIROPAYAMAZON_PAYINVOICEAFTERPAY_CLEARPAYKLARNA
If passed, must also be accompanied by one of stripe_customer_token, paypal_customer_token or authorizedotnet_customer_token in processor_payment_method_token.
processor_customer_tokenstring
The customer token at the processor.
processor_namestring
This will impact validation on billing_details.
Possible values
stripebraintreeauthorizeshopify_paymentsmolliecustom_gateway
Currently, shopify_payments is in read-only mode and can only be managed by Shopify.
processor_payment_method_tokenstring
The payment token at the processor.
statusstring
State of the Payment Method.
Possible values
unvalidatedvalidinvalidempty
status_reasonstring
The status reason for the payment method.
Often used when invalid to provide background details in invalidity.
updated_atdatetime
Last time the Payment_method was updated.
billing_addressobject
An object with the customer’s address information.
Show child attributesHide child attributes111 new
- address1string
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystring
  The city of the billing address.
- companystring
  The company name of the billing address.
- countrystring · nullableNew
  The full country name of the billing address.
- country_codestring
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestring
  The last name of the billing address.
- phonestring
  The phone number of the billing address.
- provincestring
  The name of the province or state associated with the billing address.
- zipstring
  The zip code or postcode of the address.

The payment method object

{
  "payment_method": {
    "id": 1234567,
    "customer_id": 62459147,
    "billing_address": {
      "address1": "123 Washington Street",
      "address2": "Suite 101",
      "city": "Los Angeles",
      "company": "Recharge",
      "country": "United States",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "1234567890",
      "province": "California",
      "zip": "90210"
    },
    "created_at": "2018-11-14T09:00:01",
    "default": true,
    "payment_details": {
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2021,
      "last4": 1234
    },
    "payment_type": "CREDIT_CARD",
    "processor_customer_token": "cus_AB3ebcBaL6pCx9",
    "processor_name": "stripe",
    "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy",
    "retry_date": null,
    "status": null,
    "status_reason": null,
    "taxable": true,
    "updated_at": "2018-11-14T09:00:01"
  }
}

#Create a payment method

POST/payment_methods

BigCommerceCustomRCS

Create a Payment Method in Recharge.

Scopewrite_payment_methods

When processor_name is mollie, the required fields are customer_id, processor_name and processor_payment_method_token. processor_customer_token is optional when processor_payment_method_token is passed. If billing_address is omitted, the billing address of the customer is used. A 429 is returned when the store limits how many payment methods a customer can add.

Body parameters

address_idsarrayNew
A list of Address IDs to associate with the new payment method. IDs that do not belong to the customer are ignored.
apply_to_all_subscription_addressesbooleanNew
If true, the new payment method is associated with all of the addresses of the customer.
customer_idintegerRequired
The Recharge customer_id.
defaultbooleanRequired
true if this is default payment method for the Customer.
payment_detailsobjectNew
Details about the specific payment method. Accepts brand, last4, exp_month, exp_year, paypal_email, paypal_payer_id, wallet_type and funding_type. For other processors the details are retrieved from the processor and this value is ignored.
Only applied when processor_name is custom_gateway or authorize, or when payment_type is PAYPAL_EXPRESS.
payment_typestringRequired
The type of payment.
Possible values
CREDIT_CARDPAYPALAPPLE_PAYGOOGLE_PAYSEPA_DEBITIDEALSHOP_PAYPAYPAL_EXPRESSSOFORTGIROPAYAMAZON_PAYINVOICEAFTERPAY_CLEARPAYKLARNA
processor_customer_tokenstring
The customer token at the processor.
On Stripe this begins with cus_.
processor_namestringRequired
This will impact validation on billing_details.
Possible values
stripebraintreeauthorizeshopify_paymentsmolliecustom_gateway
Currently, shopify_payments is in read-only mode and can only be managed by Shopify.
processor_payment_method_tokenstring
The payment token at the processor.
billing_addressobject
An object with the customer’s address information.
Show child attributesHide child attributes111 new
- address1stringRequired
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystringRequired
  The city of the billing address.
- companystring
  The company name of the billing address.
- countrystringNew
  The full country name of the billing address. Either country or country_code is required when billing_address is passed.
- country_codestring
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestring
  The last name of the billing address.
- phonestring
  The phone number of the billing address.
- provincestring
  The name of the province or state associated with the billing address.
- zipstring
  The zip code or postcode of the address.
retry_chargesboolean
Whether charges associated with this payment method should be retried. If true then charges with previous payment-related errors will be set to retry during the next automated processing.

POST/payment_methods

curl -X POST 'https://api.rechargeapps.com/payment_methods' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "customer_id": 62824147,
  "default": true,
  "payment_type": "CREDIT_CARD",
  "processor_customer_token": "cus_JGYtLWi2HS8ymD",
  "processor_name": "stripe",
  "processor_payment_method_token": "pm_34jdshjs"
}'

Response

{
  "payment_method": {
    "id": 1234567,
    "customer_id": 62459147,
    "billing_address": {
      "address1": "123 Washington Street",
      "address2": "Suite 101",
      "city": "Los Angeles",
      "company": "Recharge",
      "country": "United States",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "1234567890",
      "province": "California",
      "zip": "90210"
    },
    "created_at": "2018-11-14T09:00:01",
    "default": true,
    "payment_details": {
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2021,
      "last4": "1234"
    },
    "payment_type": "CREDIT_CARD",
    "processor_customer_token": "cus_AB3457BaL90Cx9",
    "processor_name": "stripe",
    "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy",
    "status": null,
    "status_reason": null,
    "updated_at": "2018-11-14T09:00:01"
  }
}

#Retrieve a payment method

GET/payment_methods/{id}

Retrieve an existing Payment Method using the Recharge Payment Method id.

Scoperead_payment_methods

Query parameters

includestringNew
A comma-separated list of related resources to return in the include object of the payment method. Both values require the read_customers scope.
Possible values
addressescustomer
include_deletedbooleanNew
If true, a deleted payment method can be retrieved.

GET/payment_methods/{id}

curl 'https://api.rechargeapps.com/payment_methods/1234567' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "payment_method": {
    "id": 1234567,
    "customer_id": 62459147,
    "billing_address": {
      "address1": "123 Washington Street",
      "address2": "Suite 101",
      "city": "Los Angeles",
      "company": "Recharge",
      "country": "United States",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "1234567890",
      "province": "California",
      "zip": "90210"
    },
    "created_at": "2018-11-14T09:00:01",
    "default": true,
    "payment_details": {
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2021,
      "last4": "1234"
    },
    "payment_type": "CREDIT_CARD",
    "processor_customer_token": "cus_AB3457BaL90Cx9",
    "processor_name": "stripe",
    "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy",
    "status": null,
    "status_reason": null,
    "updated_at": "2018-11-14T09:00:01"
  }
}

#Update a payment method

PUT/payment_methods/{id}

BigCommerceCustomRCS

Modify an existing Payment Method.

Scopewrite_payment_methods

Payment methods with a processor_name of shopify_payments cannot be updated through this endpoint and return a 422.

Body parameters

defaultboolean
true if this is default payment method for the Customer.
To update the Payment Method that will be used for processing charges for a specific Address, use Update an address method with a payment_method_id.
billing_addressobject
An object with the customer’s address information.
Show child attributesHide child attributes111 new
- address1string
  Line one of the billing address.
- address2string
  Line two of the billing address.
- citystring
  The city of the billing address.
- companystring
  The company name of the billing address.
- countrystringNew
  The full country name of the billing address.
- country_codestring
  2-letter country code.
- first_namestring
  The first name of the billing address.
- last_namestring
  The last name of the billing address.
- phonestring
  The phone number of the billing address.
- provincestring
  The name of the province or state associated with the billing address.
- zipstring
  The zip code or postcode of the address.
payment_detailsobjectNew
Details about the specific payment method. Accepts brand, last4, exp_month, exp_year, paypal_email, paypal_payer_id, wallet_type and funding_type.
Only applied to payment methods with a processor_name of custom_gateway.
payment_typestringNew
The type of payment. Must be supported by the processor of the payment method.
Possible values
CREDIT_CARDPAYPALAPPLE_PAYGOOGLE_PAYSEPA_DEBITIDEALSHOP_PAYPAYPAL_EXPRESSSOFORTGIROPAYAMAZON_PAYINVOICEAFTERPAY_CLEARPAYKLARNA
processor_customer_tokenstringNew
The customer token at the processor. Only applied when processor_payment_method_token is also passed.
processor_payment_method_tokenstringNew
The payment token at the processor. The token is validated with the processor and the payment details are refreshed from it.
retry_chargesbooleanNew
Whether charges with a previous payment failure should be retried after the payment method is updated. Defaults to true.

PUT/payment_methods/{id}

curl -X PUT 'https://api.rechargeapps.com/payment_methods/1234567' \
  -H 'X-Recharge-Version: v2' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "default": true
}'

Response

{
  "payment_method": {
    "id": 1234567,
    "customer_id": 62459147,
    "billing_address": {
      "address1": "123 Washington Street",
      "address2": "Suite 101",
      "city": "Los Angeles",
      "company": "Recharge",
      "country": "United States",
      "country_code": "US",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "1234567890",
      "province": "California",
      "zip": "90210"
    },
    "created_at": "2018-11-14T09:00:01",
    "default": true,
    "payment_details": {
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2021,
      "last4": "1234"
    },
    "payment_type": "CREDIT_CARD",
    "processor_customer_token": "cus_AB3457BaL90Cx9",
    "processor_name": "stripe",
    "processor_payment_method_token": "pm_1LdKdfj2zqHvUId1uGheBEHy",
    "status": null,
    "status_reason": null,
    "updated_at": "2018-11-14T09:00:01"
  }
}

#Delete a payment method

DELETE/payment_methods/{id}

BigCommerceCustomRCS

Permanently delete a Payment Method.

Scopewrite_payment_methods

DELETE/payment_methods/{id}

curl -X DELETE 'https://api.rechargeapps.com/payment_methods/1234567' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{}

#List payment methods

GET/payment_methods

Return a list of payment methods in your store.

HTTP request examples

GET /payment_methods

Scoperead_payment_methods

Results are always sorted by id, newest first. The response also contains next_cursor and previous_cursor.

Query parameters

customer_idstring
Gets all Payment methods for this customer.
address_idintegerNew
Gets all Payment methods associated with this Address.
idsstringNew
Filter payment methods by id. If passing multiple values, must be comma separated.
includestringNew
A comma-separated list of related resources to return in the include object of each payment method. Both values require the read_customers scope.
Possible values
addressescustomer
include_deletedbooleanNew
If true, deleted payment methods are also returned and each payment method includes a deleted_at attribute.
processor_namestringNew
Filter payment methods by processor. Can only be passed together with customer_id.
Possible values
stripebraintreeauthorizeshopify_paymentsmolliecustom_gateway
processor_payment_method_tokenstringNew
Filter payment methods by the payment token at the processor. Only applied when customer_id is also passed.
limitintegerNew
The number of results. Default is 50, maximum is 250.
pageintegerNew
The page to show. Default is 1.
cursorstringNew
The cursor returned in next_cursor or previous_cursor of a previous response. When a cursor is passed, limit is the only other parameter that can be passed with it.

GET/payment_methods

curl 'https://api.rechargeapps.com/payment_methods?limit=3' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "payment_methods": [
    {
      "id": 1234567,
      "billing_address": {
        "address1": "123 Washington Street",
        "address2": "Suite 101",
        "city": "Los Angeles",
        "company_name": "Acme Corp",
        "country": "United States",
        "country_code": "US",
        "name": "Jane Doe",
        "phone": "1234567890",
        "province": "California",
        "zip": "90210"
      },
      "created_at": "2018-11-14T09:00:01",
      "customer_id": 999123999,
      "default": true,
      "payment_details": [
        {
          "brand": "visa",
          "exp_month": 12,
          "exp_year": 2021,
          "last4": 1234
        }
      ],
      "payment_type": "CREDIT_CARD",
      "processor_customer_token": "cus_AB3ebcBaL6pCx9",
      "processor_name": "stripe",
      "processor_payment_method_token": "pm_123123",
      "updated_at": "2018-11-14T09:00:01"
    }
  ]
}