How to Charge a Payment Method

In order to charge a payment method, you'll need a payment method's ID, and information about the transaction you'd like to create using it. These make up the input for the chargePaymentMethod GraphQL mutation.

If you charge a single-use payment method, this will consume it and you will no longer be able to look up, charge, or vault that payment method.

Mutation

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

Variables

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

Full Request

To plug this mutation into a curl request, compose the query and variables into a JSON-valid string and use it as the payload. For example:

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 ExampleCharge($input: ChargePaymentMethodInput!) {
    chargePaymentMethod(input: $input) {
      transaction {
        id
        status
      }
    }
  }",
  "variables": {
    "input": {
      "paymentMethodId": "id_of_payment_method",
      "transaction": {
        "amount": "11.23"
      }
    }
  }
}'

There are many more possible fields you can use in the input or request in the output; see the Explorer for more.

Response

A successful charge results in a transaction with the SUBMITTED_FOR_SETTLEMENT status:

{
  "data": {
    "transaction": {
      "id": "id_of_transaction",
      "status": "SUBMITTED_FOR_SETTLEMENT"
    }
  }
}

An unsuccessful charge results in a transaction with one of several failure statuses, which will give you more information about the type of failure.

Transaction IDs

After charging a payment method, you may want to store the ID of the resulting transaction in your database for future reference, either for presenting back in the UI at a later time, or for your own internal book-keeping, analysis, or reporting requirements. You can retrieve this transaction by its ID using the node query.

Transaction Statuses

Even if the chargePaymentMethod mutation doesn't return any errors, the transaction it created may not have processed succesfully. For instance, the customer's card-issuing bank may have declined the charge, or your fraud protection settings may have blocked it. In this case, the Transaction will have a failure status, such as Processor Declined or Gateway Rejected, and further information on what caused the failure. You can then use this to decide how to handle the failure and how to report it back to your customer.

A successful transaction will be updated over time as funds are debited from the customer and sent to you. As money moves, the transaction passes through multiple states in the payment lifecycle, most typically from Authorized to Submitted for Settlement, to Settling, to Settled.

Using the complete list of transaction statuses and their meanings, you can check the status of a transaction to determine if it was successful or unsuccessful and why, and if successful, what will happen to the transaction next.

See also:

• The Transaction Lifecycle
• A simplified status diagram

Error Handling

Unsuccessful transactions are a normal part of transaction processing and should not be considered exceptional. If an error occurs, you will either not receive a transaction object on the payload, or you will receive only a partial object.

Here's an example of an error on a transaction.

{
  "data": {
    "chargePaymentMethod": null
  },
  "errors": [
    {
      "message": "Amount must be greater than zero.",
      "path": ["chargePaymentMethod"],
      "extensions": {
        "errorType": "user_error",
        "errorClass": "VALIDATION",
        "legacyCode": "81531",
        "inputPath": ["input", "transaction", "amount"]
      }
    }
  ],
  "extensions": {
    "requestId": "abc-123-def-456"
  }
}

See more details on handling errors in Making API Calls.

Testing

We provide test single-use payment methods in Sandbox, which can be used instead of tokenizing a new payment method every time. Pass any of these payment method "nonces" as the paymentMethodId in the chargePaymentMethod mutation. Or, to test vaulted payment methods, use one of these test single-use payment methods in a vaultPaymentMethod mutation, then pass the resulting payment method's ID into the chargePaymentMethod mutation.

To test processor responses, you can use these test values as the transaction amount.