Commerce Escrow

CONTENTS OF THIS FILE

• Introduction
• Requirements
• Configuration

INTRODUCTION

This module integrates Drupal Commerce with Escrow.com including the Escrow Pay [1] and the Escrow Offer [2].

1. https://www.escrow.com/pay/docs
2. https://www.escrow.com/offer/docs

Features

• Both methods are implemented as offsite payment gateways.
• Webhook integration for real time updates.
• Payments in Drupal Commerce synchronized with Escrow.com.
• Supports voids through the order management interface
• Product variation bundle type EscrowItem with several escrow-specific fields.
• Order and payment workflow synchronized via webhook integration for automated workflow.

REQUIREMENTS

This module should be added to your codebase via Composer

composer require "drupal/commerce_escrow"

You must also have an Escrow account or developer access to the account you intend to configure for your integration. You can sign up for one here.

There are no other requirements than Commerce Core 3

CONFIGURATION

Payment gateway configuration

Once you've installed the module, you must navigate to the Drupal Commerce payment gateway configuration screen to define a payment gateway configuration. This will require providing an API key, email of Escrow.com account holder and configuring the mode (Live vs. Test).

Order type configuration

Go to Commerce => Configuration => Order Types and edit a desired order type which you want to use with Escrow integration and under workflow choose Escrow Workflow.

Product variation configuration

Go to Commerce => Configuration => Product variation types and edit a desired product variation type which you want to use with Escrow integration and under traits choose Escrow Item.

Now that product variation type will get several Escrow specific fields.

• Brokered: if you are brokering sale of this product between a seller and buyer.
• Broker Fee percentage: specify the fee which you will charge for brokering service.
• Broker Fee split: split the broke fee to a buyer or seller or equally to both sides.
• Escrow Fee: split the escrow fee to buyer or seller or equally to both sides.
• Escrow item type: defining the typo of goods to be sold via Escrow.com
• Inspection period: how long the Escrow offer is valid, between 1 and 30 days.
• Display Escrow fee information: you can during checkout show estimated fee to be charged on Escrow.com
• Extra attributes fees: adds additional fee to be charged on Escrow.com
• Single item: defines if the product variation is allowed only once to be sold.
• In stock: a flag to determine if product is in stock, depends on Single item logic.

Webhook configuration

All Escrow payment gateways share one webhook URL with a secret token, shown under Commerce > Configuration > Payment > Escrow settings: https://yourwebsite.com/payment/webhook/escrow/{token}

Register that URL as a webhook on Escrow.com, once on each Escrow.com account the gateways use. The order decides which gateway handles an event. Keep the URL private like the API key.

The token is generated the first time it is needed, and stored as webhook_secret in commerce_escrow.settings, so a configuration export includes it. It is better to set it in settings.php from an environment variable, which keeps it out of the database and exported configuration, and gives each environment its own:

$config['commerce_escrow.settings']['webhook_secret'] = getenv('ESCROW_WEBHOOK_SECRET');

Generate the value with openssl rand -hex 32. It may hold only letters, digits, - and _. If the variable is not set, the webhook stays closed rather than falling back to another value, and the settings page says so. Without an override, you can regenerate the token on the same page if it leaks.

Configuration imports remove settings that aren't exported, so if your deployment imports configuration, also export commerce_escrow.settings. With the override in place the exported value stays empty.

Escrow.com retries webhooks, so the same event can arrive more than once. Webhooks of one order are handled one at a time, and a repeat changes nothing on the order or payment. Subscribers to ESCROW_WEBHOOK get repeats too and should allow for them.

An Escrow Offer started outside of checkout goes through the commerce_escrow.offer_orders service. Escrow.com copies the order's id from the auction to the transaction, and the payment keeps the auction's token, so both exist before the buyer is sent to Escrow.com, but only as a locked draft order: out of checkout and not refreshed. The first webhook places it with the offer_made transition, as an offer isn't a sale: receipts, invoices and taking the item off sale don't follow from it. Drafts whose buyer never made the offer are deleted by cron after 30 days.

Escrow.com does not sign webhooks. Every webhook is therefore verified by fetching the transaction from the Escrow.com API. The transaction must belong to the order and confirm the event before the order or payment is updated.

Custom configuration / modifications.

You don't need to use the provided order and payment workflow. The provided product variation type Escrow item is a requirement to be used.

The automated order and payment states can be stopped via event subscriber \Drupal\commerce_escrow\Event\EscrowEvents::ESCROW_WEBHOOK and setStopWebhook method. Use getTransaction() of that event for the transaction verified with the Escrow.com API, rather than trusting the webhook payload.

You can enrich or alter transaction payload via event subscriber \Drupal\commerce_escrow\Event\EscrowEvents::ESCROW_ORDER_PAYLOAD

The http client for communication with Escrow.com has all available methods for interacting with Escrow.com API. If you want to use it in your custom code, you can easily initiate it like this:

$client = new EscrowClient('api_key', 'account_email', 'test');
$payload = [
  'currency' => 'usd',
  ......
];
$client->createTransaction($payload);

Maintainers

Developed and maintained by Vallic, a Drupal development company and the team behind Vallic Cloud, Drupal hosting.