Usage

At checkout

The customer chooses the Braintree method and places the order. The store opens its own pay page of that order: the amount, the card fields (Braintree Hosted Fields) and, with PayPal on, the PayPal button. On “Pay” the card goes through 3D Secure 2 (the bank may show a challenge), the store checks the 3D Secure result with Braintree and charges the card. The customer lands on the order confirmation.

• A declined card or a failed 3D Secure check shows a clear message; nothing is charged and the customer can try another card on the same page.
• If the order total changed after the page was opened, nothing is charged and the page reloads with the new amount.
• An order that is already paid (also by other means), cancelled, or (Multi-Vendor) partly cancelled by the store is not offered for payment.
• “Cancel and return to the shop” gives the order the “not paid” status; the customer gets the cart back at checkout.
• If Braintree does not answer clearly (a timeout), the store looks the payment up by its order id. If it still cannot tell, the order page is shown with the note “Braintree has not confirmed your payment yet”, the cart is emptied (also the saved cart of a signed-in customer) so the order cannot be paid twice, and the cron books the payment as soon as Braintree reports it. The payment is never shown as cancelled while it is unclear.

On the order page

Orders > the order > Braintree tab:

• Status (local and Braintree), transaction id, orderId, merchant account, card brand and last four digits or PayPal, 3D Secure result, amounts (authorized, captured, refunded), dispute status, every attempt and every operation.
• Capture (authorizations): once, up to the authorized amount; a lower amount leaves the rest uncollected.
• Void: an authorization, or a charge that is not settling yet. The customer is not charged.
• Refund: full or partial, several times, up to the captured amount, once Braintree reports the payment settling or settled (usually within a day). Before that, void it instead.
• Read back: reads the transaction from Braintree (also picks up actions taken in the Control Panel) and settles operations without a clear answer.

Automatic actions

• Authorize only + capture by status: the capture status captures the authorization; the void status (or Declined) voids it. The capture never changes the order status.
• Refund status: gives the money of the order back (or, on Multi-Vendor, the vendor order’s share): a charge that is not settling yet is voided, otherwise refunded once Braintree allows it.
• A failed automatic void or refund is queued and retried; the cron also re-queues payments that are flagged but still hold money.
• A payment for an order whose total changed while the charge was running, a second payment of a paid order, or a payment that lands after the order was cancelled is voided or refunded automatically and flagged on the order tab; it is never booked as paid. The Braintree list shows a red banner while such a payment still holds money or a settlement was declined.
• Dispute webhooks are recorded on the order tab and in the log (and, if you chose one, set the dispute status).

Multi-Vendor

• Owner mode: a cart with several vendors is paid once, on the parent order. Each vendor order shows that payment and refunds only its own share. With “Authorize only”, the authorization is captured once every vendor order reached the capture status or is cancelled; a cancelled vendor’s share is not captured. When every vendor order is cancelled, the authorization is voided. If a vendor order is cancelled while a charge is still on its way, its share is refunded automatically once the payment settles.
• Vendors see the Braintree tab of their orders; in owner mode only the marketplace owner captures, voids and refunds.
• Owner mode off: each vendor’s orders are paid to the vendor’s own Braintree account and the vendor captures, voids and refunds them in the vendor panel.

Lists, log and jobs

Orders > Braintree: every payment with its status (search by order, orderId or transaction id), the Connection, Log (filters, CSV export) and Jobs pages (queued refunds and read-backs, Retry, Remove, Run now).