Refund Authorizations: API Updates and Sandbox Testing

Update (June 9, 2020): Updated post to reflect sandbox availability.

The payments industry is moving to an authorization model for refund processing. Refund authorizations introduce real-time decline responses to refunds. This blog post provides details on Braintree’s plans for refund-related API changes: we recommend that you review the technical changes outlined here as well as the guidelines in our previous post to ensure your integration is prepared for refund declines.

Technical changes

To reduce integration friction, Braintree will introduce two refund decline workflows. The workflow that you experience will depend on the SDK version your integration uses to connect to Braintree: new SDK versions or previous SDK versions.

New SDK versions

In Q1 2020, Braintree will release the following new SDK versions:

  • Ruby 3.0 or newer
  • Python 4.0 or newer
  • Java 3.0.0 or newer
  • Node.js 3.0.0 or newer
  • PHP 5.0.0 or newer
  • .NET 5.0.0 or newer

If your integration uses one of these new SDK versions, and the processor declines a refund, the response will have the processor response code available. The processor response code will pull from the existing pool of 2000-class decline codes, allowing you to determine the cause of the decline in real time. Common refund decline codes include:

  • 2004 - Expired Card
  • 2005 - Invalid Card Number
  • 2014 - Fraud Suspected
  • 2047 - Pick Up Card

Note: GraphQL users will receive processor response codes for all refund declines.

Previous SDK versions

If your integration uses an SDK version older than those listed above, and the processor declines a refund, you will receive one of the following two validation errors in lieu of a processor response code:

  • Hard decline: 915200 - Failed to refund transaction.
  • Soft decline: 915201 - Failed to refund transaction. Please try again at a later time.

Sandbox testing

These changes are currently available in the Braintree sandbox. We recommend testing refund declines so that you can prepare for the upcoming launch of refund authorizations.

In order to simulate a refund decline in sandbox, follow these steps:
1. Simulate a successful sale using an amount between $3001.00-4000.99
2. Submit the sale for settlement; once the transaction updates to a Settled or Settling status, it is eligible for a refund
3. Specify the sale’s transaction ID in a refund request
4. In order to simulate a refund decline, specify a refund amount between $2000-2999.99
5. The amount specified will determine the decline code: for example, submitting a refund for $2004.00 will generate a decline response of 2004 - Expired Card if using a current SDK version

General guidelines

Our previous post provides a comprehensive list of rules and guidelines – here are a few key requirements:

  • If the refund attempt is hard declined, do not reattempt the refund to the same card.
  • If the initial refund attempt declines, you are permitted to refund an alternate card that matches the same card brand used to create the original sale. This reattempt must be performed via a detached credit.
  • It is against scheme rules to refund a card that does not match the same brand used to create the sale. For example, you cannot refund a Mastercard if the original sale was created with a Visa card.
  • If all attempts to refund the cardholder are declined, you are permitted to issue a refund via store credit, check, or alternative method, depending on your refund policy.


If you have any questions about these changes, contact us.

Tim Whicker Tim is a Product Manager under Braintree's Cards Compliance team. In his free time, he's a tech, music, and design enthusiast. More posts by this author

You Might Also Like