Initializing the Reader for Charging

When you're ready to charge a customer, you should create an In-Store Context by requesting a charge from a card 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.

Charging is similar to authorizing, except that if the authorization is successful, Braintree will automatically capture the transaction. This is also known as creating a Sale Transaction.

To provide idempotency on the request charge 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

--header 'Idempotency-Key: 94c9ea8b-31b0-488e-a231-57e32f0bfd70'

mutation RequestChargeFromInStoreReader($input: RequestChargeFromInStoreReaderInput!) {
                requestChargeFromInStoreReader(input: $input) {
                    clientMutationId
                    id
                    status
                    reader {
                        id
                        name                
                        status
                    }
                }
            }

Checking the Reader Charge 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 RequestChargeInStoreContext.statusfield as the transaction goes through the lifecycle.

When the RequestChargeInStoreContext.status changes to "COMPLETE", you will also receive a transaction object RequestChargeInStoreContext.transactionin the response. Save the completed RequestChargeInStoreContext.transaction.id in your database for referencing the transaction in subsequent operations.

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

Testing the Unhappy Paths in Sandbox:

{
                node(id: "{{last_braintree_instore_context}}") {
                 ... on RequestChargeInStoreContext {
                  id
                  status
                  statusReason
                  reader {
                   id
                   name
                   status
                  }
                  transaction {
                   id
                   orderId
                   status
                   statusHistory {
                    ... on PaymentStatusEvent {
                     status
                     timestamp
                     terminal
                     ... on AuthorizedEvent {
                      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
                     }
                    }
                   }
                  }
                 }
                }
               }

Charge Flow Example Sequence Diagram

The following high-level sequence diagram depicts an example charge flow; however, this flow can vary depending on whether you are vaulting, and polling logic may also vary by application. This is just an example flow.

Recommended Timeout Logic

Knowing that every application will have different flows and architectural constraints the following recommended timeout logic is just a suggestion based on best practices, but every integration may be different.

Generally, the card reader has a built-in timeout logic of 180 seconds for a “maximum checkout time,” that is, from the moment you request a charge from the card reader, it will hang for 180 seconds if no payment instrument is presented. However, it is recommended for the POS application to have its own timeout logic to make sure the POS stays in sync with the card reader and provides a seamless experience to the customer.

Recommended sequence for initializing card reader and polling for transaction result:

Cancelling a Charge

If you need to stop a transaction from being paid while the reader is activated and requesting payment, you can cancel the InStoreContext. Cancelling an InStoreContext places the reader back into idle mode and returns you to the PayPal-branded screensaver. It is important to note that canceling a charge is only possible when a payment instrument has not yet been presented to the card reader. After the card reader has been presented with payment, the only way to stop that would be with a reversal or refund of payment.

mutation RequestCancelFromInStoreReader(
                $input: RequestCancelFromInStoreReaderInput!
            ) {
                requestCancelFromInStoreReader(input: $input) {
                    id
                    status
                    reader {
                        id
                        name
                        status
                        location {
                            id
                            name
                        }
                    }
                }
            }

Partial Authorizations

Partial Authorizations refer to transactions where a card with limited available funds is used to complete a purchase, and the available funds are less than the amount to be collected. This can occur with a debit card or a prepaid gift card. For example, if a merchant wants to charge $100, and the customer presents a card with only $50 available. With a partial authorization, the available $50 would be authorized or charged, while the POS system would need to recognize that there is a remaining balance to tender of $50. The POS should generally handle this like a split tender once it is determined that a partial authorization has occurred.

The way for the POS to know that a partial authorization has occurred would be to parse out the statusReason from the context ID node query, which would show as PARTIALLY_AUTHORIZED. The context status will be returned as COMPLETE.

In the Sandbox environment, you may test partial authorizations by using the "amount":"1004" in your request.

Partial Authorization Enablement

There are 2 ways to enable partial authorization on your account. You may have your PayPal Solutions Engineer or Integration Engineer enable this feature on your account. Alternatively, you may pass an API flag to determine whether you want to allow partial authorizations on the particular transaction using the acceptPartialAuthorization object. This API flag is a boolean ("true/false") variable that will override the Braintree account-level configuration. We recommend using this API flag if you would like to allow for partial authorization on some transactions and not others, or if you want more control of the enablement of this feature.

Refunding Your Customer

There are 3 ways of refunding your customer once a charge has been completed.

1) Performing a Referenced Refund:

To perform a referenced refund, you must have the transactionId from the authorization that you are attempting to refund against. This results in a refund that is linked to the original authorization. Typically, this is the preferred refund method as it allows for easy accounting. It is important to note that referenced refunds can either be in full or of a partial amount of the original authorization; however, the refund amount can not exceed the full authorized amount.

mutation refundTransaction($input: RefundTransactionInput!) {
                refundTransaction(input: $input) {
                  refund {
                    id
                    amount {
                      value
                    }
                    orderId
                    status
                    refundedTransaction {
                      id
                      amount {
                        value
                      }
                      orderId
                      status
                    }
                  }
                }
              }

Referenced Refund Example Sequence Diagram:

2) Using the Reversal API call

Sometimes, the POS might not know whether the original authorization has already been settled or not. In this scenario, it might be best to use a reversal call, which lets Braintree determine whether the transaction can be Voided or Refunded depending on the settlement status. For more details on how this works, follow this link and see the example below:

mutation reverseTransaction($input: ReverseTransactionInput!) {
                reverseTransaction(input: $input) {
                  reversal {
                      __typename
                    ... on Transaction {
                      id
                      legacyId
                      orderId
                      status
                      statusHistory {
                        status
                        terminal
                      }
                    }
                    ... on Refund {
                      id
                      legacyId
                      orderId
                      status
                      amount {
                        value
                      }
                      refundedTransaction {
                        id
                        amount {
                          value
                        }
                        orderId
                        status
                      }
                    }
                  }
                }
              }

Reversal API Call Example Sequence Diagram:

3) Performing an Unreferenced Refund or "Blind Credit":

To perform an unreferenced refund, your customer must be present at the time of refund, and a payment instrument must be presented to the card reader. The resulting refund will not be linked to the original authorization, so this is typically not the preferred way of refunding due to accounting reasons. Here are some of the common use cases below:

• Refunds to customers without a receipt (when original order cannot be found)

• Refunds to customers whose original authorization occurred while on your previous payment solution

• Refunds to an alternate payment instrument or tender type

mutation RequestRefundFromInStoreReader($input: RequestRefundFromInStoreReaderInput!) {
                requestRefundFromInStoreReader(input: $input) {
                    clientMutationId
                    inStoreContext {
                        id
                        status
                        reader {
                            id
                            name                
                            status
                        }
                    }
                }
            }

Once the refund is complete, you'll need to check the status of the context ID, similar to how this is done for a charge request. A status of "COMPLETE" indicates a successful refund.

query ID($inStoreContextId: ID!) {
                node(id: $inStoreContextId) {
                    ... on InStoreContext {
                        id
                        status
                        reader {
                            id
                            name
                            status
                        }
                        transaction {
                            id
                                    }
                                    refund {
                                        id
                                        orderId
                                        legacyId
                                        status
                                        paymentMethodSnapshot {
                                            __typename
                                            ... on CreditCardDetails {
                                                brandCode
                                                bin
                                                last4
                                                expirationMonth
                                                expirationYear
                                                }
                                            }
                                        }
                                    }
                                }
                            }

Unreferenced Refund Example Sequence Diagram:

4) Reversing a Refund

If a refund was performed and you need to reverse that refund within the acceptable reversal window, you can use the reverseRefund mutation. Keep in mind that you would need to have saved the refundId from the API response of the original refund attempt. See below example of a refund reversal. You will notice that the refundId is a required variable input to perform the reversal.

mutation reverseRefund($input: ReverseRefundInput!) {
                reverseRefund(input: $input) {
                  refund {
                    ... on Refund {
                      id
                      status
                      statusHistory {
                        status
                        terminal
                      }
                    }
                    ... on Refund {
                      id
                      amount {
                        value
                      }
                      orderId
                      status
                      refundedTransaction {
                        id
                        amount {
                          value
                        }
                        orderId
                        status
                      }
                    }
                  }
                }
              }

Refund Reversal Example Sequence Diagram:

5) Using Auth Adjustments for partial reversals

There may be some use cases where you want to perform a partial reversal rather than fully reverse a payment. The example scenario is if a customer wants to return a single item that was part of a larger purchase, and the transaction may be in an authorized state (which would make a partial refund not possible). In this scenario, you may use the updateTransaction API mutation to adjust the auth amount to the total purchase amount minus the partial reversal amount.

Receipt Data Handling

To maintain EMV compliance you may need to add additional data elements to be displayed on the receipt you offer your customers. The table below highlights the data elements that are mandatory for EMV compliance and other data elements that are optional. Be sure to include the mandatory data elements listed in the "GraphQL API Field" column when you check the reader charge status so that you can parse them from the API response.

The following are data elements that are mandatory for transactions that were declined:

The following are data elements that are mandatory for transactions that were EMV chip declined:

Manual Key Entry Transactions

There are some use cases in which you may want to support the processing of a transaction without using the card reader by entering in the card details into another application UI. This could be for over-the-phone orders (MOTO) or as a manual key entry (MKE) fallback for when the card is not readable by the card reader, in which case you may want to enter the card details into the POS UI. To facilitate this while keeping your tech stack outside of PCI scope, we have a couple of solutions that can work for you.

1) Braintree Hosted Fields

The Braintree Hosted Fields enables you to render Braintree encrypted input fields in your application user interface. This allows for the manual key entry of card details directly into Braintree encrypted input fields. See how the Braintree Hosted Fields solution works.

2) Braintree Drop-in UI

The Braintree drop-in UI allows you to render Braintree encrypted forms in your application user interface. This would allow for the manual key entry of the card details directly into the Braintree Encrypted fields. The drop-in UI is a simple integration leveraging pre-built dynamic Braintree containers. See how the Braintree Drop-in UI solution works.

Important Tips for building out your charge/refund flows

1. Always make sure you are passing your Braintree Merchant Account ID (MAID) in your charge and refund requests. This should be added as an API variable, for example:

2. Use Idempotency Keys to prevent duplicate charges to your customers

3. Align your application with our recommended timeout logic

4. Make sure you are parsing key EMV receipt data from your API response to populate on your customer receipts for EMV compliance

5. Utilize the orderId API field to pass important data for reporting and reconciliation