Skip to main content

Credit Cards

Creating simple transactions

Using chargePaymentMethod mutation is the simplest way to create a credit card transaction.

You can create a transaction with just an amount and a single-use payment method relayed from your client and immediately submit for settlement. You may see single-use payments methods referred to as a payment_method_nonce in your client. See here for more information regarding this terminology difference.

mutation

mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
  chargePaymentMethod(input: $input) {
    transaction {
      status
      id
      legacyId
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": 15.00
    }
  }
}

response

{
  "data": {
    "chargePaymentMethod": {
      "transaction": {
        "status": "SUBMITTED_FOR_SETTLEMENT",
          "id": "id_of_transaction",
          "legacyId": "legacy_id_of_transaction"
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

If you want to save a payment method for future transactions, you will need to save it to your Vault. If you want to save a payment method to your Vault upon a successful transaction, see the vaultPaymentMethodAfterTransactingInput field on TransactionInput. Follow the Vaulting a Payment Method guide for step-by-step instructions on vaulting payment methods without an associated transaction.

Creating advanced transactions

For more advanced use cases, like passing the billing address, tokenized CVV, or 3D Secure authentication, use the chargeCreditCard mutation, which accepts additional inputs.

mutation

mutation ChargeCreditCard($input: ChargeCreditCardInput!) {
  chargeCreditCard(input: $input) {
    transaction {
      id
      legacyId
      createdAt
      amount {
        value
        currencyCode
      }
      status
      billingAddress{
        addressLine1
        adminArea1
        adminArea2
        postalCode
      }
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "options": {
      "billingAddress": {
        "addressLine1": "123 Main St",
        "adminArea1": "CA",
        "adminArea2": "San Jose",
        "postalCode": "95086"
      }
    },
    "transaction": {
      "amount": "1.00"
    }
  }
}

response

{
  "data": {
    "chargeCreditCard": {
      "transaction": {
        "id": "id_of_transaction",
        "legacyId": "legacy_id_of_transaction",
        "createdAt": "date_time_of_transaction",
        "amount": {
          "value": "1.00",
          "currencyCode": "USD"
        },
        "status": "SUBMITTED_FOR_SETTLEMENT"
        "billingAddress": {
          "addressLine1": "123 Main St",
          "adminArea1": "CA",
          "adminArea2": "San Jose",
          "postalCode": "95086"
        }
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Card verification

When a payment method is a credit or debit card, you can use card verification to establish that the card data matches a valid, open account before storing or updating it in your Vault.

Braintree strongly recommends verifying all cards before they are stored in your Vault by enabling card verification in the Control Panel.

If you want to run a verification on a credit card already stored in your Vault, you can do so using the verifyCreditCard mutation.

The gateway verifies cards by running a $0 or $1 authorization and then automatically voids it. If you'd like, you can specify a different amount via CreditCardVerificationOptionsInput for the authorization.

mutation

mutation VerifyCreditCard($input: VerifyCreditCardInput!) {
  verifyCreditCard(input: $input) {
    verification {
      id
      legacyId
      status
      paymentMethodVerificationDetails{
        __typename
        ... on CreditCardVerificationDetails{
          amount{
            value
            currencyCode
          }
        }
      }
      processorResponse {
        legacyCode
        message
      }
    } 
  }
}

variables

{
  "input":{
    "paymentMethodId":"id_of_payment_method"
  }
}

response

{
  "data": {
    "verifyCreditCard": {
      "verification": {
        "id": "id_of_verification",
        "legacyId": "legacy_id_of_verification",
        "status": "VERIFIED",
        "paymentMethodVerificationDetails": {
          "__typename": "CreditCardVerificationDetails",
          "amount": {
            "value": "0.00",
            "currencyCode": "USD"
          }
        },
        "processorResponse": {
          "legacyCode": "1000",
          "message": "Approved",
        },
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}
Important

If you use our Premium Fraud Management Tools, we strongly recommend passing deviceData each time you verify a card.

Verification results

If verification is successful, the result will contain a VerifyPaymentMethodPayload response object, which will contain a VerificationDetails response object.

response

"paymentMethodVerificationDetails": {
    "__typename": "CreditCardVerificationDetails",
    "amount": {
      "value": "1.25",
      "currencyCode": "USD"
    }
}

Otherwise, you'll receive a VerificationDetails response object directly on a Customer or PaymentMethod result. This occurs when verification is run, and it returns with a status of PROCESSOR_DECLINED or GATEWAY_REJECTED

Reasons for unsuccessful verification results

You can check the message and legacyCode of the processorResponse for the reason that verification was PROCESSOR_DECLINED. If the status is GATEWAY_REJECTED, you can check the gatewayRejectionReason field for the specific reason. Learn more about gateway rejections.

Verify and Vault

If you need to verify a credit card and subsequently save it in your Vault, you can do both in a single request using vaultCreditCard mutation. If the verification succeeds, the resulting multi-use payment method will be saved in your Vault, and the status attribute in the response will be set to VERIFIED.

mutation

mutation VaultCreditCard($input: VaultCreditCardInput!) {
  vaultCreditCard(input: $input) {
    paymentMethod {
      id
      details {
        ... on CreditCardDetails {
          brandCode
          last4
        }
      }
    }
    verification {
      id
      legacyId
      status
      processorResponse {
        legacyCode
        message
      }
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method"
  }
}

response

{
  "data": {
    "vaultCreditCard": {
      "paymentMethod": {
        "id": "id_of_payment_method",
        "details": {
          "brandCode": "VISA",
          "last4": "1111",
        }
      },
      "verification": {
        "id": "id_of_verification",
        "legacyId": "legacy_id_of_verification",
        "status": "VERIFIED",
        "processorResponse": {
          "legacyCode": "1000",
          "message": "Approved",
        },
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Reasons for unsuccessful verification results

What you should check is the status of the response. If the status is VERIFIED, the verification was successful. If the status is PROCESSOR_DECLINED, it means the verification was unsuccessful based on the response from the processor. You can get more details under processorResponse in the response. You can check the legacyCode and message for the reason that a verification was declined. If status is GATEWAY_REJECTED, the gateway has rejected it because the payment method has failed one or more fraud checks. If the status is GATEWAY_REJECTED, you can check the gatewayRejectionReason in GatewayRejectedEvent for the specific reason. Learn more about gateway rejections.

Update Billing Address

Updating a credit card's billing address can be done in multiple ways. See our updating customer information support article for more information. To update a credit card's billing address via the api you can use the updateCreditCardBillingAddress mutation. This mutation will set the new billing address for an existing multi-use credit card, and before updating, it will verify the card and new address.

mutation

mutation UpdateCreditCardBillingAddress($input: UpdateCreditCardBillingAddressInput!){
  updateCreditCardBillingAddress(input: $input){
    billingAddress{
      addressLine1
      adminArea2
      adminArea1
    }
    verification{
      id
      legacyId
      status
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "billingAddress": {
      "addressLine1": "123 Cantina",
      "adminArea2": "Mos Eisley",
      "adminArea1": "Tatooine" 
    }
  }
}

response

{
  "data": {
    "updateCreditCardBillingAddress": {
      "billingAddress": {
        "addressLine1": "123 Cantina",
        "adminArea2": "Mos Eisley",
        "adminArea1": "Tatooine"
      },
      "verification": {
        "id": "id_of_verification",
        "legacyId": "legacy_id_of_verification",
        "status": "VERIFIED"
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Authorize

If you need to authorize a credit card without submitting for settlement, you can use the authorizeCreditCard mutation. It will return a TransactionPayload object that will include transaction details. Check the status of the transaction to see if it was authorized. When authorizing a credit card you will need to ensure you submit the transaction for settlement at a later time using the captureTransaction mutation.

mutation

mutation AuthorizeCreditCard($input: AuthorizeCreditCardInput!){
  authorizeCreditCard(input: $input){
    transaction{
      id
      legacyId
      status
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "1.00"
    }
  }
}

response

{
  "data": {
    "authorizeCreditCard": {
      "transaction": {
        "id": "id_of_payment_transaction",
        "legacyId": "legacy_id_of_transaction",
        "status": "AUTHORIZED"
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Creating a Detached Refund

Detached credits are disabled by default and generally violate card association rules. However, it may be appropriate to issue detached credits in some instances. For more information about detached credits, see the detached credits article. To issue detached credits, you can use the refundCreditCard mutation.

mutation

mutation($input: RefundCreditCardInput!) {
  refundCreditCard(input: $input) {
    refund {
      id
      status
      amount {
        value
      }
      orderId
      merchantAccountId
      source
    }
  }
}

variables

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "refund": {
      "amount": "10.00",
      "orderId": "id_of_order"
    }
  }
}

response

{
  "data":{
    "refundCreditCard": {
      "refund": {
        "id": "id_of_refund",
        "status": "SUBMITTED_FOR_SETTLEMENT",
        "amount": {
          "value": "10.00"
        },
        "orderId": "id_of_order",
        "merchantAccountId": "id_of_merchant_account",
        "source": "API"
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}
Note

This mutation is disabled by default. To request that we temporarily enable detached credits, have the authorized signer on your Braintree gateway account contact us.

Tokenization

Important

The following mutation should only be used if you fall under the PCI SAQ-D compliance level. If you are unsure of your status, do NOT use this mutation. Learn more about how to collect payment information

The tokenizeCreditCard mutation will tokenize the credit card fields and return a payload for a single-use payment method.

mutation

mutation TokenizeCreditCard($input: TokenizeCreditCardInput!){
  tokenizeCreditCard(input: $input){
    paymentMethod{
      id
      legacyId
      usage
      details{
        ... on CreditCardDetails{
          brandCode
          last4
          expirationMonth
          expirationYear
        }
      }
    }
  }
}

variables

{
  "input": {
    "creditCard": {
      "number": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2024"
    }
  }
}

response

{
  "data": {
    "tokenizeCreditCard": {
      "paymentMethod": {
        "id": "id_of_payment_method",
        "legacyId": "legacy_id_of_payment_method",
        "usage": "SINGLE_USE",
        "details": {
          "brandCode": "VISA",
          "last4": "1111",
          "expirationMonth": "12",
          "expirationYear": "2024"
        }
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Once you call the tokenizeCreditCard mutation, you can pass the resulting single-use payment method into various mutations such as chargePaymentMethod and authorizePaymentMethod.