Payment Methods

A payment method represents transactable payment information such as credit card details or a customer's authorization to charge a PayPal or Venmo account. Payment methods belong to a customer, are securely stored in the Braintree Vault, and have a payment_method_token attribute that you can store on your servers (with reduced PCI compliance burden) and later use to create transactions.

Create

Use Braintree::PaymentMethod.create() to create a payment method for an existing customer:

result = Braintree::PaymentMethod.create(
  :customer_id => "131866",
  :payment_method_nonce => nonce_from_the_client
)
Ruby

Alternatively, you can create a new customer with a payment method using Braintree::Customer.create() with the payment_method_nonce parameter.

Once successfully created, you can use Braintree::Transaction.sale() with the payment_method_token parameter to create a transaction.

Credit card verification

If the payment method is a credit card, you can use options.verify_card to ensure that Braintree attempts to verify that the credit card number matches a valid, open account.

result = Braintree::PaymentMethod.create(
  :customer_id => "the_customer_id",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :verify_card => true,
    :verification_merchant_account_id => "the_merchant_account_id",
  }
)
Ruby

If you wish to always run verification regardless of the presence of verify_card, you can turn on card verification in the Control Panel.

Card verification can be performed through the customer API or the credit card API. See also:

If you are using our Advanced Fraud Tools, we strongly recommend passing device_data each time you verify a card.

Verification results

The result of a Braintree::PaymentMethod.create() may contain a verification result object. The verification result object will only be present if a verification ran and was returned with a status of "processor_declined" or "gateway_rejected". You can check the processor response code and processor response text for the specific reason that a verification was "processor_declined". Successful results will not return a verification result object.

result = Braintree::PaymentMethod.create(
  :customer_id => "the_customer_id",
  :payment_method_nonce => nonce_from_the_client,
  :options => {
    :verify_card => true
  }
)

result.success?
#=> false

verification = result.credit_card_verification
verification.status
#=> "processor_declined"

verification.processor_response_code
#=> "2000"

verification.processor_response_text
#=> "Do Not Honor"
Ruby

If the status is "gateway_rejected", you can check the gateway_rejection_reason for the specific reason. Learn more about gateway rejections.

result.success?
#=> false

verification = result.credit_card_verification
verification.status
#=> "gateway_rejected"

verification.gateway_rejection_reason
#=> "cvv"
Ruby

Update

Use Braintree::PaymentMethod.update() to update an existing payment method.

Make default

Use the make_default option to set a payment method as the default for its customer:

result = Braintree::PaymentMethod.update(
  "the_token",
  :options => {
    :make_default => true
  }
)
Ruby

Billing address

Update the billing address:

result = Braintree::PaymentMethod.update(
  "the_token",
  :billing_address => {
    :street_address => "1 E Main St",
    :extended_address => "Suite 3",
    :locality => "Chicago",
    :region => "IL",
    :postal_code => "60622",
    :options => {
      :update_existing => true
    }
  }
)
Ruby

You can also omit the update_existing option to create a new billing address for just this payment method.

See the reference and more examples of updating a payment method. If you want to update both payment method and customer information together, use Braintree::Customer.update().

Find

Use Braintree::PaymentMethod.find() to find a payment method:

payment_method = Braintree::PaymentMethod.find("token")
Ruby

If the payment method cannot be found, it will raise a Braintree::NotFoundError exception.

The return value of the Braintree::PaymentMethod.find() call will be a Braintree::PaymentMethod response object.

Delete

Use Braintree::PaymentMethod.delete() to delete a payment method:

Braintree::PaymentMethod.delete("the_token")
Ruby

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or email our Support team.