Card verification overview

Verification is only available for credit cards.

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 as well as fraud rules when we run verification. For more information on verifications, see this support article.

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.

In some cases, cardholders may see a temporary authorization 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::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

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

Customers

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 => {
    :payment_method_nonce => "nonce-from-the-client",
    :options => {
      :verify_card => true
    }
  }
)
Ruby

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 => {
    :payment_method_nonce => "nonce-from-the-client",
    :options => {
      :verify_card => true
    }
  }
)
Ruby

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 => {
    :payment_method_nonce => "nonce-from-the-client",
    :options => {
      :update_existing_token => "the_payment_method_token",
      :verify_card => true
    }
  }
)
Ruby

Payment methods

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

result = Braintree::PaymentMethod.create(
  :customer_id => "the_customer_id",
  :payment_method_nonce => "nonce-from-the-client",
  :options => {
    :verify_card => true
  }
)
Ruby

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

result = Braintree::PaymentMethod.update("the_payment_method_token",
  :payment_method_nonce => "nonce-from-the-client",
  :options => {
    :verify_card => true
  }
)
Ruby

To verify the AVS information of an existing payment method, pass the update request with an empty array and the verify_card set to "true". It will not verify the CVV as this value is never stored in the Vault.

Results

The result of a customer or payment method create may contain a verification result object. The verification result object will only be present if a verification ran and the verification comes back processor_declined or gateway_rejected. Successful results will not return a verification result object. 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(
  :payment_method => {
    :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, 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.success?
#=> false

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

verification.gateway_rejection_reason
#=> "cvv"
Ruby