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 paymentMethodToken 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([
    'customerId' => '12345',
    'paymentMethodNonce' => nonceFromTheClient
]);
PHP

Alternatively, you can create a new customer with a payment method using Braintree_Customer::create() with the paymentMethodNonce parameter.

Once successfully created, you can use Braintree_Transaction::sale() with the paymentMethodToken parameter to create a transaction.

Credit card verification

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

$result = Braintree_PaymentMethod::create([
  'customerId' => 'the_customer_id',
  'paymentMethodNonce' => nonceFromTheClient,
  'options' => [
    'verifyCard' => true,
    'verificationMerchantAccountId' => 'the_merchant_account_id',
  ]
]);
PHP

If you wish to always run verification regardless of the presence of verifyCard, 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 deviceData 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([
    'customerId' => 'the_customer_id',
    'paymentMethodNonce' => nonceFromTheClient,
    'options' => [
        'verifyCard' => true
    ]
]);

$result->success;
// false

$verification = $result->creditCardVerification;
$verification->status;
// "processor_declined"

$verification->processorResponseCode;
// "2000"

$verification->processorResponseText;
// "Do Not Honor"
PHP

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

$result->success;
// false

$verification = $result->creditCardVerification;
$verification->status;
// "gateway_rejected"

$verification->gatewayRejectionReason;
// "cvv"
PHP

Update

Use Braintree_PaymentMethod::update() to update an existing payment method.

Make default

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

$updateResult = Braintree_PaymentMethod::update(
  'the_token',
  [
    'options' => [
      'makeDefault' => true
    ]
  ]
);
PHP

Billing address

Update the billing address:

$result = Braintree_PaymentMethod::update(
  'the_token',
  [
    'billingAddress' => [
        'streetAddress' => '100 Maple Lane',
        'options' => [
            'updateExisting' => true
        ]
    ]
]);
PHP

You can also omit the updateExisting 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:

$paymentMethod = Braintree_PaymentMethod::find('token');
PHP

If the payment method cannot be found, it will throw a Braintree_Exception_NotFound 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');
PHP

Still Have Questions?

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