Initiate a Sale or Refund
This article covers both sale and refund transactions
Last updated
Was this helpful?
This article covers both sale and refund transactions
Last updated
Was this helpful?
When you're ready to charge a customer, you should create an In-Store Context by . 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 .
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
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.
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.
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.
Step 1
Generate unique Idempotency key (UUID) to be added in your request header
Step 2
Use an HTTP timeout window of 10 seconds if you do not get back a response
Step 3
Send the request again using the same Idempotency key, this allows you to recover the request session and avoid sending a duplicate request
Step 4
Once you get an InstoreContext.Id start polling against it to retrieve the transaction.Id and final transaction status
Step 5
Use an HTTP timeout window of 3 seconds if you do not get a response while polling against the InStoreContext.Id
Step 6
The Partial Auth feature has undergone a rebuild as of October 2023. The information below represents the new behavior and integration path.
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.
In the Sandbox environment, you may test partial authorizations by using the "amount":"1004" in your request.
There are 3 ways of refunding your customer once a charge has been completed.
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.
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
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.
Data Element
Description
Mandatory vs. Optional
GraphQL API Field
Merchant Name
The name of the merchant.
M
Transaction.merchantName
Merchant Address Details
The address details of the merchant.
M
Transaction.merchantAddress
Transaction Date and Time
The date and time of the transaction.
M
Transaction.createdAt
Merchant ID (MID)
The unique reference of the merchant.
O
Transaction.merchantId
Terminal ID (TID)
The unique reference of the terminal.
O
Transaction.paymentMethodSnapshot .origin.details.terminalId
Transaction Number
The unique reference number of the transaction.
M
Transaction.legacyId
Invoice Number
The unique reference number of the receipt.
M
Transaction.legacyId
Card Type
The name of the card issuer.
M
Transaction.paymentMethodSnapshot.creditCard.brand
Account Number
The account number printed on the card. All digits except for last 4 must be truncated.
M
Transaction.paymentMethodSnapshot.creditCard.last4
Application Preferred Name
The name of the application used to process the transaction (e.g. MasterCard).
M
Transaction.paymentMethodSnapshot .origin.details.applicationPreferredName
Application Identifier
The unique reference number of the EMV application used for the transaction.
M
Transaction.paymentMethodSnapshot .origin.details.applicationIdentifier
Approval Code
The authorization code received from the processor for the transaction.
M
Transaction.statusHistory[…].processorResponse.authorizationId
Authorization Mode
The authorizing entity (e.g. Issuer).
M
Transaction.paymentMethodSnapshot .origin.details.authorizationMode
Transaction Kind
The type of the transaction (e.g. Sale/Refund).
M
Transaction.kind
Card Entry Method
The method used to read the detail of the card (e.g. Chip).
M
Transaction.paymentMethodSnapshot.origin.details.inputMode
Purchase Details
A brief description of the purchased goods or services along with their prices.
M
Transaction.lineItems* * - If not provided in the authorize/charge request, then these details must be provided by the merchant.
Transaction Amount
The grand total amount for the transaction.
M
Transaction.amount.value
Currency
If specified, the currency that the transaction was processed in. If no currency is identified on the receipt, the transaction is deemed to have taken place in the currency that is legal tender at the point of sale.
O
Transaction.amount.currencyCode
PIN Verify Statement
The cardholder’s PIN verification status specific to the processed transaction (e.g. Verified).
M
Transaction.paymentMethodSnapshot.origin.details.pinVerified
Return and Refund Policies
The terms and conditions for return and refund set forth by the merchant.
M
Merchant or POS generated message that indicates return policy
The following are data elements that are mandatory for transactions that were declined:
Decline Code
The system generated decline code for the declined transaction.
M
Transaction.statusHistory[…].processorResponse.legacyCode
Decline Message
The merchant generated message for the respective decline code.
M
Merchant or POS generated message that reflects the decline code
The following are data elements that are mandatory for transactions that were EMV chip declined:
Terminal Verification Results
A series of bits set by the terminal upon reading EMV card data, where each bit represents information about the transaction. This value is contained in the response EMV data under tag 95.
M
Transaction.statusHistory[…].processorResponse.emvData
Issuer Authentication Data
Issuer provided data received in response to an online authorization request to be delivered to the EMV chip card. This value is contained in the response EMV data under tag 91.
M
Transaction.statusHistory[…].processorResponse.emvData
Authorization Response Code
The 4-character code generated by the Issuer in response to an online authorization request that represents the authorization status of the transaction. This value is contained in the response EMV data under tag 8A.
M
Transaction.statusHistory[…].processorResponse.emvData
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.
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 RequestChargeInStoreContext.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, look at .
:
Generally, the card reader has a built-in timeout logic of 180 seconds for a “maximum checkout time,” that is, from the moment you 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.
Send the every 2-3 seconds until you get the final transaction.status, transaction.Id
If you need to stop a transaction from being paid while the reader is activated and requesting payment, you can 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.
Note that if you request to cancel the InStoreContext and the API returns a context status of "COMPLETE" that would indicate that the charge has already been processed. In this scenario, you should again to get the transactionId and perform a reversal or to cancel the charge.
The way for the POS to know that a partial authorization has occurred would be to parse out the from the context ID node query, which would show as PARTIALLY_AUTHORIZED. The will be returned as COMPLETE.
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 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.
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, and see the example below:
If a refund was performed and you need to reverse that refund within the acceptable reversal window, you can use the 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.
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 API mutation to adjust the auth amount to the total purchase amount minus the partial reversal amount.
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 so that you can parse them from the API response.
EMV-compliant receipts are not enforced by PayPal/Braintree. We make all necessary data for compliance available through our API and highly suggest following EMV compliance rules. For more information about EMV-compliant receipts, see the .
Please take a look at our EMV-compliant, including an explanation with an EMV-compliant data element as an overlay.
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 solution works.
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 solution works.
Always make sure you are passing your Braintree (MAID) in your charge and refund requests. This should be added as an API variable, for example:
Use to prevent duplicate charges to your customers
Align your application with our
Make sure you are parsing key from your API response to populate on your customer receipts for EMV compliance
Utilize the to pass important data for reporting and reconciliation
