Initiate a Card Present Authorization
This page covers the support of separate auth from capture on the Braintree In-Person solution from a card present perspective.
Last updated
Was this helpful?
This page covers the support of separate auth from capture on the Braintree In-Person solution from a card present perspective.
Last updated
Was this helpful?
For some use cases where a capture delay is required (ex: endless aisle, save the sale, tipping on receipt, hotel check-in), you may need to request an authorization rather than requesting a charge. This gives the API caller complete control over the authorization capture cadence rather than relying on automated Braintree capture logic. Generally, this operates similarly to e-commerce authorization flows, with some important differences.
When you're ready to charge a customer, you can create an In-Store Context by requesting to authorize a card on the reader. In this step, your application will specify at minimum, the readerId , merchantAccountIdand transaction.amount details to initialize the reader for payment acceptance. Note that the merchantAccountIdis not validated against in the Sandbox environment; however, this is a required value in the Production environment for all interactions with the card reader.
Authorizing is similar to charging, except that if the authorization is successful, Braintree will NOT capture the transaction. It would be up to the merchant to send a separate capture request using the transaction.id to complete the charge.
Card present authorizations only allow for a single capture request; multiple partial capture is NOT supported. Any remaining authorized funds after the first capture will automatically be voided.
To provide idempotency on the mutation, you must also include the HTTP header Idempotency-Key with a unique value. UUIDv4 is recommended. For example, if using curl to make the request, you would include
When the RequestAuthorizeInStoreContext.status changes to "COMPLETE", you will also receive a transaction object RequestAuthorizeInStoreContext.transactionin the response. Save the completed RequestAuthorizeInStoreContext.transaction.id in your database for referencing the transaction in subsequent operations (ie. capture, adjust auth, void, etc...).
MCC codes such as 4821 (Taxi Cabs and Rideshares) and 5812 (Restaurants) are allowed to capture up to 20% more than the authorized amount.
MCC codes such as 7011 (Lodging), 7512/7513/7519 (Vehicle Rentals), as well as Cruise Lines, Grocery merchants, and Retailers are allowed to capture up to 15% more than the authorized amount.
If you have a direct contract with AMEX, you may need to reach out to them to have them configure your account to allow for over-captures.
Some MCC codes are allowed to capture more (aka over capture) than the authorized amount (typically used by restaurant merchants for tipping purposes)
Some MCC codes are allowed to use incremental authorizations (adjust auth) in order to incrementally increase the auth amount (typically used by Hotel & Hospitality merchants)
To enable over-captures or incremental authorizations, your Braintree account must be configured accordingly. Please work with your Solutions Engineer or Integration Engineer to facilitate this
Incremental Auth is not supported for AMEX transactions. For some use cases, you may need to perform an over-capture for an AMEX transaction
After the reader is initialized for payment, your application must wait for the customer to interact with it (i.e. insert a test card) and for the payment attempt to be processed. Your application should use to poll on a 2-second interval between responses for the current status of the payment using the RequestChargeInStoreContext.id received at charge initialization and monitor the RequestAuthorizeInStoreContext.statusfield as the transaction goes through the lifecycle.
All successful test transactions should have a transaction amount value below $2,000 for testing. For more info on using amounts to simulate various transaction outcomes, take a look at .
To capture the authorized funds, you must use the within a 24-hour window of the funds being authorized (except for eligible Lodging MCC codes, which have expiry windows of up to 30 days). For a card-present authorization, you are allowed only a single capture attempt. Any remaining authorized funds not captured after the initial capture request will be voided. You may capture a lesser amount than what was authorized or an amount up to the maximum over-capture threshold (subject to eligibility). For merchants processing on MCC codes ineligible for over-capture, the maximum amount allowed for capture is the amount authorized.
For some merchants, for example, those in the Hotels & Hospitality or some other industries, incremental authorizations (aka adjust auth) are an important feature for use cases such as tipping adjustment, hotel room damages, or hotel mini-bar charges, etc... This feature is subject to merchant eligibility based on MCC code, and it is also not supported for AMEX transactions and some other transaction types. This feature leverages the with Braintree's GraphQL API.
Using an estimated authorization or a "pre-auth" can help avoid issuer rejections and improve authorization rates for scenarios when you may not know the final charge amount at the time of authorization. Some industries where this may be common are hotels, vehicle rentals, bars, etc... It is recommended that you use this feature if you are using incremental auth. To trigger an estimated authorization you must pass the flag with a value of "ESTIMATED". See example below:
is supported for
transactions are NOT supported for separate auth from capture
Passing of is not supported in the authorization request; however, you may pass this data in the request
