Announcing GA (General Availability) of our GraphQL API

It has been over a year since we started to use GraphQL at Braintree. In that time, the API has grown to serve a significant amount of our production traffic, including critical functionality such as credit card tokenization and client initialization. We are very excited to announce the GA (general availability) of our public GraphQL API, a new way for merchants to integrate with Braintree’s payment and reporting functionality.

Braintree’s GraphQL API can be used as an optional alternative to our server-side SDKs. For example, you can now easily build an end-to-end checkout experience by combining our client-side JavaScript, iOS, and/or Android SDKs with our GraphQL API. This next-generation API is straightforward to integrate and offers great control, flexibility, and extensibility of our global payments platform.

What is GraphQL?

GraphQL is a query language for APIs developed by Facebook in 2012 and has been adopted by companies such as Airbnb, GitHub, Yelp and PayPal. GraphQL gives clients the flexibility to request exactly what is needed and nothing more. Construct a request by defining the resources you want via a POST request to a server and receive a response that matches the format of your request. Please check out our About GraphQL guide to learn more about the basic concepts of GraphQL.

Why use GraphQL?

In comparison to our SDKs, GraphQL offers a potentially more efficient, flexible integration. Specify exactly what data you care about and retrieve as much or as little as needed, all through a single endpoint. You have the freedom to use any programming language you want. Without SDKs to manage and update on your server, your payment integration is simpler, more maintainable, and portable. With the API, you can integrate once and take advantage of new features as they are released, without having to update an SDK.

We make it easy for you to test API calls in our Sandbox environment by using our API Explorer, directly in your browser. We also have a fully searchable reference page to browse our schema. If you are already using our server-side SDKs and want to migrate to the GraphQL API, check out our migration guide.

What’s an example of a GraphQL API call?

This is an example of creating a transaction using the Braintree GraphQL API. The API accepts a request body with query and variables combined into a JSON string like this:

{
  "query": "
    mutation ChargePaymentMethod ($input:ChargePaymentMethodInput!){
      chargePaymentMethod(input:$input) {
        transaction {
          id
          status
        }
      }
    }",
  "variables": {
    "input": {
      "paymentMethodId": "single_use_payment_method_from_the_client",
      "transaction": {
        "amount": "10.00"
      }
    }
  }
}

Put it all together into a curl request with the necessary headers:

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

The JSON response will look like this:

{
  "data": {
    "chargePaymentMethod": {
      "transaction": {
        "id": "dHJhbnNhY3Rpb25fbWI4MTZhYmQ",
        "status": "SUBMITTED_FOR_SETTLEMENT"
      }
    }
  },
  "extensions": {
    "requestId": "LuSqpWyygEfOMyl6zMWO7yGAAuNwmrTYRtDgM7-muT6PgsSYglOpbg=="
  }
}

What does GraphQL API support?

Here’s a high-level view of everything it handles now. Check out the schema for a more in-depth view:

• Tokenize, vault, and verify payment methods
• Authorize and capture transactions
• Single-step charges
• Refunds and reversals
• Transaction, Refund, Verification, Customer, and Dispute search
• Customer management
• Transaction level fee report
• Level 2 & 3 transaction fields
• Enhanced ACH support
• Payment method verification and vaulting
• PSD2/3DS support

Future plans

We will continue to expand the feature set of our GraphQL API, so stay tuned! Check out our changelog for a full list for recent updates and watch it for new capabilities. If you’d like to request a feature, feel free to open a Github issue.

If you’d like to get started and learn more about our GraphQL API, check out our developer documentation.