Braintree

In this page you will find the required information to perform REST calls related to the Braintree payment provider.

Payment Method	Payment	Refund	Automatic Subscription	Manual Subscription
pay-pal	✓	✓	✓

	Enabled
Pay By Link	✗

Endpoints

Every Braintree endpoint has this prefix path /v3/braintree

Pay

POST /{payment-method}/pay

This endpoint allows to execute payments via the Braintree payment provider.

The request body requires the providerData field which requires the following data:

• customerId: id of the customer. Vaulted payment uses this field to identify the customer, thus make sure to give the same id that you saved in the vault.
• storeInVault: boolean that specifies whether to store the customer inside the vault. Set it to true if performing Checkout + Vault.
• vaulted: boolean that specifies whether the customer is already vaulted or not.

For more information, please read BrainTree's documentation, paying particular attention to the Vault, Checkout and Checkout with Vault sections.

danger

Checkout + Vault is only supported on JS frontends; iOS and Android apps must perform Vaulting and Checkout separately.

Refund

POST /refund

This endpoint allows to refund an already executed payment via the Braintree provider.

The request body does not require any provider-specific data.

Subscription

Schedule

POST /subscription/schedule

This endpoint allows to start a new subscription via the Braintree provider.

The request body requires the providerData object: the following options are available:

• paymentToken

{
  [...]
  "providerData": {
     "paymentToken": "1234567890" // paymentToken related to the payment method saved on Braintree Vault for the user.
  },
}

• nonce

{
  [...]
  "providerData": {
    "nonce": "1234567890",     // Nonce related to the user's payment method.
    "customerId": "0000000007" // Braintree customer identifier.
  },
}

The subscriptionInfo.interval field accept the following values:

• MONTH

Update

POST /subscription/update/{subscriptionToken}

This endpoint allows to update subscription info.

Expire

POST /subscription/expire/{subscriptionToken}?shopTransactionId={{shopTransactionId}}

This endpoint allows to expire a subscription.

Status

GET /status?paymentId={paymentId}

This endpoint allows to get the current status of the payment identified by the required query parameter paymentId.

Check

GET /check?paymentId={paymentId}

This endpoint allows to get the current status of the payment identified by the required query parameter paymentId and also send a notification to the external service as specified by PAYMENT_CALLBACK_URL environment variable.

Callback

POST /callback

This endpoint should only be called by Braintree.

Utility

Customer Token

GET /utility/customer/token

BrainTree frontend SDKs often necessitate a customer token in order to perform operations such as showing the billing agreement terms and conditions or the PayPal checkout page. This endpoint allows to retrieve the customer token given the required query parameter customer_id.

The response contains the token and a boolean which informs whether the token is vaulted or not:

• if the customer isn't vaulted or his data has been revoked, a new, temporary token is generated and returned
• if the customer is vaulted, his token is returned

Example:

{
  "client_token": "h89h8934g793ru9by3rbh939fb",
  "vaulted": true
}

Payment Submit

POST /utility/payment/submit

When a new transaction is generated with the option submitForSettlement set to false, it needs to be submitted for settlement later on, in order to allow braintree to capture money from the customer's account. This endpoint allows to submit for settlement the transaction identified by the required query parameter transaction_id.

The response is a message description of the performed action result.

danger

The /submit POST call has been implemented, but it's never been tested in production.

Create Customer

POST /utility/customer/create

This endpoint allows to create a new customer on the provider systems.

The request body requires the following data:

• customer_id
• nonce

The response is a JSON object with the nullable field client_token.

Example:

{
  "client_token": "h89h8934g793ru9by3rbh939fb"
}

Braintree Dashboard Configuration

Some configurations are needed on the provider dashboard in order to be able to manage automatic payments related to subscription:

1. create a new webhook to the Payment Gateway Manager /v3/braintree/callback endpoint
2. enable the following notifications:
   • Subscription Canceled
   • Subscription Charged Successfully
   • Subscription Unsuccessfully
   • Subscription Expired