Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Braintree Payment / GraphQL
For those unfamiliar with Braintree or payments processing, Braintree's homepage is a good place to start to learn more, along with the developer documentation which provides a good overview of the available tools and API's.
This crate allows easy access to Braintree via the GraphQL interface. It offers predefined, common queries and manages connection details.
The advantage of GraphQL is the ability to write custom, specific queries with only those input fields that you need and your individual selection of response fields.
- Design and test your queries in the Braintree API Explorer.
- Store those graphql queries in your crates
queries
directory, for instancequeries/some_filename.graphql
. - Run the "braintree-queries" tool via
cargo run --bin braintree-queries
in that directory. The tool generates rust structs and methods to perform your queries in a type safe manner. Have a look at theexamples/
directory.
Cargo features
- rustls-tls: Use rustls instead of native-tls (openssl on Linux). If you want to compile this crate with MUSL, this is what you want. Don't forget to disable the default features with --no-default-features.
How to get started
The first thing you want to do is create a sandbox account.
A sandbox environment can be used to test your integration without needing to go through the full application process.
Once you've created an account, follow the instructions to retrieve your Merchant ID, Public Key, and Private Key and
store them in a credentials.json
file. Use credentials.json.example
as a template.
Never commit this file! You should add it to your .gitignore
file now.
In your rust program, initialize the Braintree
object via those credentials.
use Error;
use ;
use from_str;
You might want to adapt the http clients configuration ( reqwest )
to your needs via the [Braintree::with_client
] constructor.
Module organisation
With the bt
object you perform GraphQL queries (comparable to HTTP GET)
and mutations (similar to POST, PUT).
The bt.perform(query)
method aims to hide GraphQL details away.
The query
argument refers to a Query name. For example "CreateCustomer".
This crate comes with predefined queries / mutations for customer management
and one-time / recurring transactions. Find the GraphQL files in queries/
and
get an overview of available queries, parameters and return types.
The queries are organised in a hierarchical module layout, starting with queries
.
Customer related queries live in the submodule customer
, transactions in the
submodule transactions
.
Query structs reside in modules with the kebab-case formatted name of the respective
query (ie, a query with the name CreateCustomer
lives in a corresponding module with
the name create_customer
).
For example to bring CreateCustomer
into scope, you would do the following
use *;
Create, Update, Delete Customers as well as create client tokens
All customer related operations are shown below with an example each.
use ;
use *;
The bt.perform
method performs a synchronous network operation and returns with a Result
.
Network failures, invalid and bad requests but also legit errors (like "Gateway denied")
result in a returned Error.
Proper error handling is shown further down on an invalid charge_payment
request.
While mutations (create, update, delete) have a reasonable response layout, that cannot be said about queries, like the next one to retrieve a customer by ID.
Braintree implements a pageable API which results in some deeply nested response structures.
Use unwrap_customer
to extract the customer object.
A client token is necessary for the Web UI to initialize with a customer context.
All Braintree GraphQL mutations allow to optionally hand a mutation_id.
Such an ID is an identifier used to reconcile requests and responses.
Some operations like DeleteCustomer
do not return anything
else but the mutation_id.
There are a few more, rare bits related to customers, not covered by this crates' queries. Check the Braintree API Explorer.
Transactions
If decimal accuracy is required, like in the finance sector, a proper
decimal number representation is necessary.
This library uses rust_decimal
.
Create a decimal number via the macro dec!
, ie dec!(12.12)
or
convert a string representation or an integer. Use floating point numbers at your own risk!
Once you have this, you are able to create your first transaction. Find transaction related queries in this section.
Charge single-use payment method
Vault payment
A vaulted payment response contains a new payment method ID which can be used the same like a single-use payment method ID.
Remove vaulted payment method
Search for a transaction
use unwrap_search_result;
Get transaction by ID
use unwrap_get_result;
Error Handling
Transactions (and other operations) may fail.
If the error is related to Braintree (in contrast to network errors),
the braintree_error
method will return a structure with the following information:
message
The human-readable error message. This value is not intended to be parsed and may change at any time.path
A "path" vector with the GraphQL query or mutation causing the error. For example ["ChargePaymentMethod","Input","paymentMethodId"]error_class
A string that represents the error class. Can be any of AUTHENTICATION, AUTHORIZATION, INTERNAL, UNSUPPORTED_CLIENT, NOT_FOUND, NOT_IMPLEMENTED, RESOURCE_LIMIT, SERVICE_AVAILABILITY, VALIDATION
A quote from the Braintree website:
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.
Disclaimer and Limitations
Note that this is an unofficial library, provided as-is, with no support whatsoever by Braintree. The generator tool uses a modified branch of the graphql-client crate until 0.9 is released.
MIT licensed. Pull requests are welcome.
Cheers, David Graeff