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 Single-Use 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 is represented by the PaymentMethod type, with its usage field containing a value of SINGLE_USE. The ID for this tokenized, single-use payment method information is the only thing you need to vault it.

For the remainder of this guide, we will refer to the payment method represented by the nonce as a "single-use payment method", and the nonce itself as its ID.

Vault the Payment Method

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

This mutation will automatically run a verification against payment methods that support them before storing them in the vault. The verification result is represented both at the top level as vaultPaymentMethod.verification, and on the payment method itself in vaultPaymentMethod.paymentMethod.verifications.

Note that the single-use payment method 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
      usage
      details {
        __typename
        ... on CreditCardDetails {
          cardholderName
        }
        ... on PaypalAccountDetails {
          payer {
            email
          }
        }
        ... on VenmoAccountDetails {
          username
        }
        ... on UsBankAccountDetails {
          accountHolderName
        }
      }
    }
    verification {
      status
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "<single-use-payment-method-id>"
  }
}

curl

curl  -H 'Content-Type: application/json'  -H 'Authorization: Basic BASE64_ENCODED(PUBLIC_KEY:PRIVATE_KEY)'  -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
        usage
        details {
          __typename
        }
      }
      verification {
        status
      }
    }
  }",
  "variables": {
    "input": {
      "paymentMethodId": "<single-use-payment-method-id>"
    }
  }
}'

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

response

{
  "data": {
    "vaultPaymentMethod": {
      "paymentMethod": {
        "id": "<multi-use-payment-method-id>",
        "usage": "MULTI_USE",
        "details": {
          "__typename": "CreditCardDetails",
          "cardholderName": "Jane Q. Cardholder"
        }
      },
      "verification": {
        "status": "VERIFIED"
      }
    }
  }
}

or, if the payment method does not require a verification:

response

{
  "data": {
    "vaultPaymentMethod": {
      "paymentMethod": {
        "id": "<multi-use-payment-method-id>",
        "usage": "MULTI_USE",
        "details": {
          "__typename": "PaypalAccountDetails",
          "payer": {
            "email": "emailfor@paypal.account"
          }
        }
      },
      "verification": nil
    }
  }
}

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

Customers

If you want to group payment methods together in the Braintree API by indivdual customer, you can pass a customerId in the vault request. Once vaulted, a payment method cannot be transferred to a different customer, but the customer can be updated with new personal information. All payment methods belonging to a customer will be available on the paymentMethods connection field on the customer.

The default behavior when vaulting a payment method, without a customerId, is to create an empty customer associated with the newly-vaulted payment method. This can be ignored if unused, or updated later to hold relevent information.

Error Handling

The only required parameter on input is paymentMethodId. Failing to supply this will result in an error.

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

the payment method verification failed (for payment methods that require it)
the single-use payment method has already been consumed
the single-use payment method has expired
the single-use payment method represents invalid payment information
the single-use payment method represents payment information that isn't vaultable

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

Payment Method Verification Failed

In order to mitigate fraudulent payment method usage, the vaultPaymentMethod mutation will automatically run verifications against payment methods that support them (e.g. credit cards). You can control which merchant account to run the verification against using the verification.merchantAccountId input field.

If the verification fails or is declined, the payment method will not be stored in the vault. In this case, you will need to check the vaultPaymentMethod.verification response field to understand why the verification failed.

Here is an example response from a failed verification:

errors

{
  "data": {
    "vaultPaymentMethod": {
      "paymentMethod": null,
      "verification": {
        "status": "PROCESSOR_DECLINED"
      }
    }
  },
  "errors": [
    {
      "message": "Payment method failed verification.",
      "path": ["vaultPaymentMethod", "paymentMethod"],
      "extensions": {
        "errorClass": "VALIDATION",
        "inputPath": ["input", "paymentMethodId"]
      }
    }
  ]
}

This response represents a GraphQL "partial failure", in which a failure to fetch one part of the response (verifyCreditCard.paymentMethod) doesn't affect the ability to fetch another (verifyCreditCard.verification). In this case, the errors entry is used to describe what happened to cause the verifyCreditCard.paymentMethod field to be null, while the data entry still contains useful information about the verification result in vaultPaymentMethod.verification.

There are certain cases where a single vaultPaymentMethod request could result in multiple verifications (for example \$1 verification retries). To fetch these results, refer to the vaultPaymentMethod.paymentMethod.verifications field, which returns all historical verifications run on the payment method. This field is represented as a paginated VerificationConnection, rather than a simple list. Read more about this type in our Connections and Pagination guide.

Single-Use Payment Method is Consumed

The vaulting mutation could also fail if the paymentMethodId you provide has already been consumed. These IDs are single-use, so if you've already used it to create a transaction, for instance, you cannot vault it. Actions that consume a single-use payment method include charging, authorizing, capturing, and vaulting.

Single-Use Payment Method has Expired

Single-use payment methods expire after 3 hours. If it has been more than 3 hours since you collected payment information to create a single-use payment method, you can no longer consume it.

Single-Use Payment Method Represents Invalid Data

When the payment information a single-use payment method represents is "not valid," the vaulting mutation will return a validation error.

Single-Use Payment Method Isn't Vaultable

In some cases, the single-use payment method represents payment information that is not vaultable. For example, when authorizing a PayPal account, the customer only grants permission to charge it once. In that case, you are not permitted to retain the information in your vault. Any calls to the vaulting mutation with such a single-use payment method will result in an error.

Deleting a Vaulted Payment Method

If your customer no longer wishes their payment method to be stored for future use, or you otherwise want to remove the multi-use payment method, use the deletePaymentMethodFromVault mutation. This is non-reversible; to store the same payment method again, you would need to obtain a new single-use payment method from the customer for it, and re-vault it, which would create a new multi-use payment method (with a new ID) representing the same underlying payment method.

Deleting a Vaulted Venmo Account

If you use the deletePaymentMethodFromVault mutation to remove a multi-use Venmo payment method, it will also delete the Venmo customer's merchant connection within their Venmo app in "Connected Businesses". However, if your vault has duplicate Venmo payment methods for the same underlying customer Venmo account, the merchant connection will not be deleted until the last payment method is deleted.

Keep in mind that a Venmo customer can also delete a merchant connection from within their Venmo app at any time. This will automatically remove the Venmo payment method from your vault. You can be notified when this happens via the PaymentMethodRevokedByCustomer webhook; see the Webhooks Guide for information on setting up webhooks outside of the GraphQL API.