Implement Braintree Checkout
Implement Braintree checkout to authorize, capture, purchase, and refund payments. The following instructions use Braintree Sandbox environment. Please refer to Braintree Payments for production environments.
Prerequisites
- Ensure that you have a Commerce account, and Client ID and Client Secret of your store available from Commerce Manager.
- Get an access token.
- Create an account in Braintree Payments Sandbox.
- Enable Braintree in Commerce Manager
Procedure - Set up the Checkout Flow
Use the API to create a checkout flow. Ensure a cart exists, and it has already been checked out. See Checkout.
Pay by Customer ID
workflow
In Braintree sandbox, create a new customer WITH Credit Card. (NOTE: you need the customer ID for the payment). This
will be customerID
for the following requests. The customerID
value can be found from Vault in the navigation.
-
Use the following request example to set up
purchase
from Braintree. Replace thepayment
with thecustomerID
.curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
-H "Authorization: Bearer XXXX" \
-d '{
"data": {
"gateway": "braintree",
"method": "purchase",
"payment": "customerID"
}
}'The following response example is returned:
200 OK
"data": {
"id": "77e6928d-bbbe-40fd-b448-4d84d3a10ab9",
"type": "transaction",
"reference": "cf8wnwd9",
"gateway": "braintree",
"amount": 11000,
"refunded_amount": 0,
"currency": "USD",
"transaction_type": "purchase",
"status": "complete",
"relationships": {
"order": {
"data": {
"type": "order",
"id": "5d12c9a8-47ff-4b18-b1ae-19d7827b216d"
}
}
},
"meta": {
"display_price": {
"amount": 11000,
"currency": "USD",
"formatted": "$110.00"
},
"display_refunded_amount": {
"total": {
"amount": 0,
"currency": "USD",
"formatted": "$0.00"
}
},
"timestamps": {
"created_at": "2025-06-25T22:27:13Z",
"updated_at": "2025-06-25T22:27:13Z"
}
},
"payment_details": {
"detailed_status": ""
}
}
Pay by Token
workflow
If the customer has multiple credit cards, use the "Pay by Token" workflow to specify which credit card to use. The token value can be found in Customer "Payment Methods" from the Braintree Dashboard.
-
Use the following request example to set up
purchase
from Braintree. Replace thepayment
with the payment token.curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
-H "Authorization: Bearer XXXX" \
-d $'{
"data" : {
"gateway" : "braintree",
"method" : "purchase",
"payment": "actual-payment-token",
"options": {
"payment_method_token": true
}
}
}'
Pay by Nonce
workflow
Nonce example values can be found from: https://developers.braintreepayments.com/reference/general/testing/ruby#nonces-representing-cards
The nonce values should be used to fill in the payment
value in the requests.
-
Use the following request example to set up
purchase
from Braintree. Replace thepayment
with thenonce
value.curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
-H "Authorization: Bearer XXXX" \
-d $'{
"data" : {
"gateway" : "braintree",
"method" : "purchase",
"payment": "fake-valid-nonce",
"options": {
"payment_method_nonce": true
}
}
}'
Supporting Multiple Currencies
To support multiple currencies through Braintree, users must create separate merchant accounts for each currency and ensure that each desired Elastic Path cart specifies its appropriate currency for payment (aside from those using the store default currency).
For reference, please see the Braintree SDK documentation for creating separate merchant accounts and the Elastic Path details for specifying currencies on carts.
Prerequisites:
- Login to Braintree sandbox https://sandbox.braintreegateway.com/.
- Go to Business > Create New Sandbox Merchant Account.
- Set the Merchant Account ID.
- Select the currency. Create.
- Repeat the steps with a different account for different currency.
Making Payment:
-
Use the following request example to set up
purchase
from Braintree.- Replace the
payment
with thetoken
value. - Replace the
merchant_account_id
value with Merchant Account ID from the Prerequisites.
curl -X POST https://useast.api.elasticpath.com/v2/orders/:orderId/payments \
-H "Authorization: Bearer XXXX" \
-d $'{
"data" : {
"gateway" : "braintree",
"method" : "purchase",
"payment": "payment-token",
"options": {
"payment_method_token": true
"merchant_account_id": "Merchant Account ID"
}
}
}' - Replace the
Authorize
workflow
You can replace purchase
with authorize
in payment requests to make authorization payments.
See Capture a transaction to charge the payments.
Refund
workflow
Users can refund paid orders through the system. Please see documentation for Refund a Payment for more details.