Announcing General Availability of our GraphQL API

Quy Le
Quy Le
Dec 3, 2019 · 3 min read

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 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 {
"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 'Braintree-Version: 2019-01-01' \
-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",
"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.

Braintree Product and Technology

Essays on design, engineering, and product development at…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store