Braintree Sandbox Contact Sales

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.

Feature Overview

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.

Separate auth and capture using the requestAuthorization API mutation is supported starting in firmware version 5.1.0

Initializing the Reader for Authorization

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 expire after 24 hours, so it is important to send your capture request within that timeframe. Note, that some Lodging MCC codes have card present auth expiry windows of up to 30 days.

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 requestAuthorize 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

Using Idempotency-Key is an important way of preventing duplicate charges to your customer in the event of an API communication failure. For example: if you request a charge from the reader, the customer completes the charge on the reader but for some reason, the POS does not get back the result of the transaction before timing out. In this scenario, the POS could recover the original transaction using the same Idempotency-Key without accidentally creating a duplicate charge.

--header 'Idempotency-Key: 94c9ea8b-31b0-488e-a231-57e32f0bfd70' 
mutation RequestAuthorizeFromInStoreReader($input: RequestAuthorizeFromInStoreReaderInput!) {
    requestAuthorizeFromInStoreReader(input: $input) {
        clientMutationId
        id
        status
        reader {
            id
            name                
            status
        }
    }
}

Checking the Reader Authorization Status

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 the node query 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.

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...).

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 Testing Your Integration. 

{
 node(id: "{{last_braintree_instore_context}}") {
  ... on RequestAuthorizeInStoreContext {
   id
   status
   statusReason
   reader {
    id
    name
    status
   }
   transaction {
    id
    orderId
    status
    statusHistory {
     ... on PaymentStatusEvent {
      status
      timestamp
      terminal
      ... on AuthorizedEvent {
       authorizationExpiresAt
       processorResponse {
        authorizationId
        emvData
        message
        legacyCode
        retrievalReferenceNumber
       }
      }
      ... on GatewayRejectedEvent {
       gatewayRejectionReason
      }
      ... on FailedEvent {
       processorResponse {
        retrievalReferenceNumber
        emvData
        message
        legacyCode
       }
       networkResponse {
        message
        code
       }
      }
      ... on ProcessorDeclinedEvent {
       processorResponse {
        legacyCode
        message
        authorizationId
        additionalInformation
        retrievalReferenceNumber
        emvData
       }
       declineType
       networkResponse {
        code
        message
       }
      }
     }
    }
    merchantAddress {
     company
     streetAddress
     addressLine1
     extendedAddress
     addressLine2
     locality
     adminArea2
     region
     adminArea1
     postalCode
     countryCode
     phoneNumber
    }
    amount {
     value
     currencyIsoCode
    }
    merchantAccountId
    merchantName
    createdAt
    channel
    customFields {
     name
     value
    }
    paymentMethodSnapshot {
     ... on CreditCardDetails {
      origin {
       details {
        ... on EmvCardOriginDetails {
         applicationPreferredName
         applicationIdentifier
         terminalId
         inputMode
         pinVerified
        }
       }
      }
      brandCode
      last4
      bin
      expirationMonth
      expirationYear
      cardholderName
      binData {
       issuingBank
       countryOfIssuance
       prepaid
       healthcare
       debit
       commercial
      }
     }
    }
   }
  }
 }
}

Capturing funds against an Authorization

To capture the authorized funds, you must use the Capture Transaction mutation 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.

The transaction must be in an Authorized state to allow for funds capture

Example Capture request

mutation CaptureTransaction($input: CaptureTransactionInput!) {
  captureTransaction(input: $input) {
    transaction {
      id
      status
    }
  }
}

Using Incremental Authorizations

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 updateTransactionAmount API mutation with Braintree's GraphQL API.

The transaction must be in an Authorized state to be eligible for adjustment

Example Update Transaction Amount request

mutation updateTransactionAmount($input: UpdateTransactionAmountInput!) {
  updateTransactionAmount(input: $input) {
    transaction {
      id
      status
      customer{
          email
          firstName
          lastName
          id
      }
    }
  }
}

AMEX Over Capture Rules

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.

Important Tips When Integrating Separate Auth from Capture

  • Card present authorizations expire after 24 hours (except for eligible Lodging MCC codes, which may be up to 30 days)

  • Request Authorization is supported for offline transactions

  • 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

  • PayPal and Venmo QRC transactions are NOT supported for separate auth from capture

  • Passing of L2/L3 data is not supported in the authorization request; however, you may pass this data in the separate capture request

PreviousInitiate a Sale or RefundNextLevel 2 and Level 3 Data Processing

Last updated