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

Each Escrow payment gateway has its own webhook URL with a secret token, shown on the payment gateway configuration form after the gateway is saved: https://yourwebsite.com/payment/webhook/escrow/{payment_gateway}/{token}

Register that URL as a webhook on Escrow.com. Keep it private like the API key, and regenerate it from the same form if it leaks. Escrow.com sends every event on the account to every registered webhook, so when several gateways share an Escrow.com account, register the URL of each of them. Each webhook processes only orders paid through its own gateway.

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);