Braintree Ruby Docs

Card Verification

If you want to verify that a credit card is tied to a valid, open account and can be successfully charged before you save it to the vault you can use credit card verification. Verification can also be used to validate AVS and CVV. We will run AVS and CVV processing rules that you have configured in the Control Panel when we run verification.

If you would like to always verify credit cards before you store them in the vault there is an option on our Processing Options page in the Control Panel that you can enable. This means verification will run on every credit card you are saving to the vault or any existing credit card that is being updated. If the credit card fails verification it will not be saved to the vault.

If you would like to selectively run verification you can disable the verification option in the control panel and send in the verify_card option set to true when creating a customer and a credit card, when adding a credit card to an existing customer, or when updating a credit card.

If you would run verifications for most credit cards but not for some you can enable the verification option in the control panel and send in the verify_card option set to false when creating a customer and a credit card, when adding a credit card to an existing customer, or when updating a credit card for those you would not like to verify.

If you never want to run verification just leave the option in the control panel disabled and do not send in the verify_card option when creating or updating credit card.

You can specify the merchant account to verify the credit card against by passing the verification_merchant_account_id option with the merchant_account_id under credit card options.

Note: In some cases, cardholders may see a temporary authorization for $1.00 on their account after their card has been verified. The authorization will fall off the cardholderâ™s account within a few days and will never settle.

result = Braintree::CreditCard.create(
  :customer_id => "the_customer_id",
  :number => "4111111111111111",
  :expiration_date => "05/2009",
  :options => {
    :verify_card => true,
    :verification_merchant_account_id => "the_merchant_account_id"
  }
)

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

Customer API

Here is an example of creating a customer with a credit card and explicitly verifying the card.

result = Braintree::Customer.create(
  :first_name => "Fred",
  :last_name => "Jones",
  :credit_card => {
    :cardholder_name => "Fred Jones",
    :number => "4111111111111111",
    :cvv => "123",
    :expiration_date => "05/2012",
    :options => {
      :verify_card => true
    }
  }
)

Here is an example of updating a customer and adding a new credit card and explicitly verifying the card.

result = Braintree::Customer.update("the_customer_id",
  :credit_card => {
    :cardholder_name => "Bob Smith",
    :number => "4111111111111111",
    :expiration_date => "05/2012",
    :options => {
      :verify_card => true
    }
  }
)

Here is an example of updating a customer and updating a credit card and explicitly verifying the card.

result = Braintree::Customer.update("the_customer_id",
  :credit_card => {
    :cardholder_name => "Bob Smith",
    :number => "4111111111111111",
    :expiration_date => "05/2012",
    :options => {
      :update_existing_token => "the_payment_method_token",
      :verify_card => true
    }
  }
)

Credit Card API

Here is an example of creating a new credit card and explicitly verifying the card.

result = Braintree::CreditCard.create(
  :customer_id => "the_customer_id",
  :cardholder_name => "John Doe",
  :cvv => "123",
  :number => "4111111111111111",
  :expiration_date => "05/2012",
  :options => {
    :verify_card => true
  }
)

Here is an example of updating a credit card and explicitly verifying the card.

result = Braintree::CreditCard.update("the_payment_method_token",
  :cardholder_name => "John Doe",
  :cvv => "123",
  :number => "4111111111111111",
  :expiration_date => "05/2012",
  :options => {
    :verify_card => true
  }
)

Verification Result Explanations:

If the verification status comes back as processor_declined, it means that the processor declined the card. This may be because the credit card number is invalid or is over its account limit. You can check the processor response code and processor response text for the specific reason.

result = Braintree::Customer.create(
  :credit_card => {
    :cardholder_name => "Fred Jones",
    :number => "5105105105105100",
    :cvv => "123",
    :expiration_date => "05/2012",
    :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"

If the status is gateway_rejected, it means that the credit card is valid but that gateway rejected the verification because of AVS or CVV rules that you have configured in the control panel.

result = Braintree::Customer.create(
  :credit_card => {
    :cardholder_name => "Fred Jones",
    :number => "4111111111111111",
    :cvv => "200",
    :expiration_date => "05/2012",
    :options => {
      :verify_card => true
    }
  }
)

result.success?
#=> false

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

verification.gateway_rejection_reason
#=> "cvv"