Skip to main content

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

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.

  1. Use the following request example to set up purchase from Braintree. Replace the payment with the customerID.

    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.

  1. Use the following request example to set up purchase from Braintree. Replace the payment 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.

  1. Use the following request example to set up purchase from Braintree. Replace the payment with the nonce 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:

  1. Login to Braintree sandbox https://sandbox.braintreegateway.com/.
  2. Go to Business > Create New Sandbox Merchant Account.
  3. Set the Merchant Account ID.
  4. Select the currency. Create.
  5. Repeat the steps with a different account for different currency.

Making Payment:

  1. Use the following request example to set up purchase from Braintree.

    • Replace the payment with the token 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"
    }
    }
    }'

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.