Navigation

Payment Integration - Braintree (BETA)

BETA version
This module is still in development. For questions and inquiries please contact academy@spryker.com

Braintree provides two methods of payment:

  1. PayPal
  2. Credit Card

To integrate Braintree payments, you need to create and configure a Braintree merchant account.

There are two types of accounts for the integration:

  1. test accounts
  2. live accounts

Both accounts share the same configuration with different values. Braintree uses the idea of having merchants for handling different requests. Each merchant is defined by a merchant ID, that can be obtained from Braintree.

We use state machines for handling and managing orders and payments. To integrate Braintree payments, a state machine for Braintree should be created.

A basic and fully functional state machine is already built and integrated into our Demoshop (BraintreePaypal01 and BraintreeCreditCard01). You can use the same state machine or build a new one. In case a new state machine is to be built, it is preferred to contact Braintree and confirm the new state machine design and functionality.

The state machine commands and conditions trigger Braintree facade calls in order to perform the needed requests to Braintree. For simplicity, the Braintree facade uses the same calls for both credit card and PayPal payments and automatically distinguishes between the payment methods from the payment entity.

Workflow

Both credit card and PayPal utilize the same request flow. It basically consists of the following requests:

Pre-check: to check the user information in order to make sure that all the needed information is correct before doing the actual pre-authorization.

  • Authorize: to perform a payment risk check which is a mandatory step before every payment. The payment is basically considered accepted when it is authorized.
  • Revert: to cancel the authorization step which basically cancels the payment before capturing.
  • Capture: to capture the payment and receive the money from the buyer.
  • Refund: to refund the buyer when returning products.

PayPal Workflow Scenarios.

Integrating Braintree PayPal Payment

Set Braintree PayPal Configuration

The configuration to integrate PayPal payments using Braintree are:

  • ENVIRONMENT: the mode of the transaction, either development, integration, sandbox, production, qa (required).
  • MERCHANT_ID: the id of the merchant used (required).
  • PUBLIC_KEY: the public key given by the defined merchant account (required).
  • PRIVATE_KEY: the private key given by the defined merchant account (required).
  • ACCOUNT_ID: merchant account id specifying the currency (Marketplace master merchant is used by default).
  • ACCOUNT_UNIQUE_IDENTIFIER: merchant account unique identifier (Marketplace master merchant is used by default).
  • IS_VAULTED: defaults to false.
  • IS_3D_SECURE: defaults to false.

You can copy over configs to your config from the Braintree module’s config.dist.php file.

Perform Requests

In order to perform the needed requests, you can easily use the implemented state machine commands and conditions. The next section gives a summary of them.

You can also use the facade methods directly which are, however, invoked by the state machine.

Credit Card

PCI Compliance
Because of PCI compliance reasons, credit card data is communicated to the third party through JS and AJAX calls (sensitive information stays browser side).

Credit Card Scenarios

Integrating Braintree Credit Card Payment

You need to hook in the BrainTreeHandlerPlugin in the StepFactory.

Set Braintree Credit Card Configuration

The configuration to integrate credit card payments using Braintree are:

  • ENVIRONMENT: the mode of the transaction, either development, integration, sandbox, production, qa (required).
  • MERCHANT_ID: the id of the merchant used (required).
  • PUBLIC_KEY: the public key given by the defined merchant account (required).
  • PRIVATE_KEY: the private key given by the defined merchant account (required).
  • ACCOUNT_ID: merchant account id specifying the currency (Marketplace master merchant is used by default).
  • ACCOUNT_UNIQUE_IDENTIFIER: merchant account unique identifier (Marketplace master merchant is used by default).
  • IS_VAULTED: defaults to false.
  • IS_3D_SECURE: defaults to false.

Perform Requests

In order to perform the needed requests, you can easily use the implemented state machine commands and conditions. The next section gives a summary of them. You can also use the facade methods directly which, however, are invoked by the state machine.

Braintree State Machine Commands and Conditions

Commands

Authorize

  • Authorize the payment by validating the given payment data
  • Response:
    • Success: Payment Details accepted
    • Declined: Request format error, payment details not accepted
  • Plugin: AuthorizePlugin

Revert

  • Revert a previous pre-authorization call
  • Always reverts the complete pre-check or authorization
  • Plugin: RevertPlugin

Capture

  • Capture of previous (p)re-authorization call Response:
    • Success: Previous (p)re-authorization still valid and accepted
    • Declined: Previous (p)re- authorization expired, request format error, or internal error
  • Plugin: CapturePlugin

Refund

  • Refund previous captured amount
  • Full and partial refunds possible
  • Response:
    • Success: Refund possible and accepted
    • Declined: Previous capture to far in the past, request format error, or internal
  • Plugin: RefundPlugin

Conditions

Name Description Plugin

IsAuthorizationApproved

Checks transaction status log for successful authorization response

IsAuthorizationApprovedPlugin

IsReversalApproved

Checks transaction status log for successful reversal response

IsReversalApprovedPlugin

IsCaptureApproved

Checks transaction status log for successful capture response

IsCaptureApprovedPlungin

IsRefundApproved

Checks transaction status log for successful refund response

IsRefundApprovedPlugin

Braintree Facade

Facade Method Param Return Description

saveOrderPayment

OrderInterface

void

Saves the payment for the coming order

preCheckPayment

CheckoutRequestInterface

BraintreeTransactionResponseInterface

Performs the Pre-check request

authorizePayment

int (Payment entity ID)

BraintreeTransactionResponseInterface

Performs the Authorization request

revertPayment

int (Payment entity ID)

BraintreeTransactionResponseInterface

Performs the Revert request

capturePayment

int (Payment entity ID)

BraintreeTransactionResponseInterface

Performs the Capture request

refundPayment

int (Payment entity ID)

BraintreeTransactionResponseInterface

Performs the Refund request

isAuthorizationApproved

OrderInterface

bool

Checks if the Authorization request is approved

isReversalApproved

OrderInterface

bool

Checks if the Revert request is approved

isCaptureApproved

OrderInterface

bool

Checks if the Capture request is approved

isRefundApproved

OrderInterface

bool

Checks if the Refund request is approved

Core Module Structure Diagram

The Braintree core module uses the following class and flow and structure.