How to Vault A Payment Method

This guide provides instructions for vaulting a single-use payment method, storing it for future use. Once vaulted, a payment method can be reused as many times as possible without your customer needing to re-enter or authenticate their payment information.

Obtain a Payment Method Nonce

Follow this guide to obtain a payment method nonce from your client.

In this context, you can think of the payment method nonce string as a unique ID for a credit card, PayPal account, or any other payment method type that you've already sent to Braintree from your client-side integration. In the GraphQL API, this would simply be referred to as a PaymentMethod. The ID for this tokenized, single-use payment method information is the only thing you need to vault it.

Vault the Payment Method

Once you have a payment method nonce from your client, you can vault the underlying payment method. To do so, use the vaultPaymentMethod mutation.

Note that the single-use payment method signified by the nonce will be consumed if it is successfully vaulted. You will not be able to use it again. Instead, the mutation will return a new, multi-use payment method representing the same payment information. Use the ID returned by the vaultPaymentMethod mutation to charge it.

Mutation

mutation ExampleVaultWithTypeFragment($input: VaultPaymentMethodInput!) {
  vaultPaymentMethod(input: $input) {
    paymentMethod {
      id
      details {
        __typename
        ... on CreditCardDetails {
          cardholderName
        }
        ... on PaypalAccountDetails {
          payer {
            email
          }
        }
        ... on VenmoAccountDetails {
          username
        }
        ... on UsBankAccountDetails {
          accountHolderName
        }
      }
    }
  }
}

Variables

{
  "input": {
    "id": "id_of_payment_method_from_client"
  }
}

Full Request

curl \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic PUBLICKEY:PRIVATEKEY_BASE64ENCODED" \
 -H "Braintree-Version: 2019-01-01" \
 -X POST https://payments.sandbox.braintree-api.com/graphql \
 -d '{
  "query": "mutation ExampleVaultSimple($input: VaultPaymentMethodInput!) {
    vaultPaymentMethod(input: $input) {
      paymentMethod {
        id
        details {
          __typename
        }
      }
    }
  }",
  "variables": {
    "input": {
      "id": "id_of_payment_method_from_client",
    }
  }
}'

Response

For a request that included the type details, the output could look like:

{
  "data": {
    "paymentMethod": {
      "id": "PAYMENT_METHOD_ID",
      "details": {
        "__typename": "CreditCardDetails",
        "cardholderName": "Jane Q. Cardholder"
      }
    }
  }
}

or

{
  "data": {
    "paymentMethod": {
      "id": "PAYMENT_METHOD_ID",
      "details": {
        "__typename": "PaypalAccountDetails",
        "payer": {
          "email": "emailfor@paypal.account"
        }
      }
    }
  }
}

See the Explorer for more possible payment method types and fields.

Error Handling

The only required parameter on input is the payment method id. Failing to supply this will result in an error.

If the vaulting mutation fails otherwise, it is most likely because:

  • the payment method nonce has already been consumed (for example, you've already charged it to create a transaction)
  • the payment method nonce has expired
  • the payment method nonce is "not valid", and represents invalid payment information
  • the underlying payment information is not vaultable (for example, when authorizing their PayPal account, the customer only grants permission to charge it once)

Depending on which error you receive, you will need to prompt your customer to re-enter or enter another payment method.

A note about verifications

Braintree offers the ability to verify certain payment methods, which allows you to run anti-fraud checks on things like credit cards which have fewer built-in fraud protections. This feature is not currently available in the GraphQL API. If you vault a credit card with this mutation, it will not be verified, regardless of your Control Panel settings. We plan to add a standalone mutation to verify payment methods, allowing you more fine-grained control over your response to potentially fraudulent cards.