Using Custom Transfers

Custom transfers provide flexibility in managing payment flows between Violet, channels, and merchants. This feature allows for greater control over when and how funds are transferred, accommodating various business models and regulatory requirements.

With custom transfers, you can:

• Delay transfers to merchants until specific conditions are met, such as order fulfillment.

• Batch transfers for multiple orders or time periods

• Process transfers at the Bag level for multi-merchant Orders

This guide will walk you through the process of implementing custom transfers, including API endpoints, best practices, and common use cases.

1

Configuring your app

To use CUSTOM transfers with Violet, your app needs to be pre-configured. This can only be done by a Violet admin. Contact Violet Support through DevRev to have your app configured for CUSTOM transfers.

2

Creating an Order

Create an Order using either the Standard Checkout flow or the Create Order API. Unless there are explicit overrides that have been configured at the merchant level, Violet will automatically reflect the capture_method and transfer_method on the Payment Transaction.

For example,

{
    "id": 148830,
    "token": "cb330bf4baaa42d39af2487b652c9d15",
    "errors": [],
    "user_id": 10658,
    "app_id": 10549,
    "developer_id": 10454,
    "customer": { ... },
    "bags": [ ... ],
    "shipping_address": { ... },
    "billing_address": { ... },
    "sub_total": 3500,
    "status": "IN_PROGRESS",
    "is_guest": true,
    "date_created": "2024-11-19T14:35:11+0000",
    "date_last_modified": "2024-11-19T14:35:11+0000",
    "priced": false,
    "wallet_based_checkout": true,
    "currency": "USD",
    "channel": "APP",
    "currency_symbol": "$",
    "payment_transactions": [
        {
            "id": 43730,
            "order_id": 148830,
            "payment_provider": "DEMOAPP",
            "amount": 3500,
            "currency": "USD",
            "capture_status": "BYPASSED",
            "capture_method": "EXTERNAL",
            "transfer_status": "PENDING",
            "transfer_method": "CUSTOM",
            "errors": [],
            "date_created": "2024-11-19T14:35:12+0000",
            "date_last_modified": "2024-11-19T14:35:12+0000"
        }
    ],
    "guest": true,
    "order_status": "IN_PROGRESS",
    "order_id": 148830
}

3

Processing transfers to Merchants

Violet exposes the following APIs to transfer pending distributions to merchants:

• Transfer pending distributions for a single order

• Transfer pending distributions for a single bag

• Transfer pending distributions for multiple orders

• Transfer pending distributions for multiple bags

Each of them perform the same actions, however, depending on your use-case you can either process distributions at the Bag level or Order level, in both singular or bulk fashion. When multiple distributions are associated with the same merchant during bulk transfers, Violet now consolidates them into a single transfer, ensuring a streamlined and efficient bulk payment process.

Understanding the Transfer Object

Each of the endpoints listed above has a unique response, but they all share the Transfer object. This object represents a payment transfer from Violet to a merchant and provides critical transaction details, including:

Identifiers: Information such as the merchant ID, payout account ID, and payment provider transfer ID. Transaction Details: Includes the transfer's status (SUCCESS or FAILED), amount, and currency. Associated Entities: References to related bags, orders, and distributions. Error Information: Detailed error messages for failed transfers, helping diagnose and resolve issues.

The Transfer object plays a central role in tracking and managing payments within the Violet system, offering a complete and transparent view of each transaction's status and details.

Sample Transfer

{
    "id": 93001,
    "payment_provider_id": "tr_1QMsWtKUtPkD123456789asdf",
    "payout_account_id": 1025,
    "amount": 3290,
    "currency": "USD",
    "status": "SENT",
    "payment_provider": "STRIPE",
    "related_orders": [
        "148830"
    ],
    "related_bags": [
        "139177"
    ],
    "related_distributions": [
        "87770"
    ],
    "date_created": "2024-11-19T14:35:47+0000",
    "date_last_modified": "2024-11-19T14:35:47+0000",
    "errors": [],
    "payment_service": "STRIPE",
    "external_id": "tr_1QMsWtKUtPkD123456789asdf"
}

Field	Type	Sample Value	Notes
merchant_id	Integer	12345	The unique identifier of the merchant that this transfer is associated with.
payout_account_id	Integer	99999	The unique identifier of the Violet payout account for the merchant that this transfer was sent to.
payment_provider_transfer_id	String	“tr_12309u123”	The unique identifier of the Stripe Transfer object. Pasting this ID in Stripe will load details in the Stripe dashboard for this transfer.
status	String	SUCCESS , FAILED	Denotes what state the transfer is in. Can either be SUCCESS or FAILED when returned by this API. Failed transfers will have a corresponding error in the errors field.
amount	Integer	10000	Amount transferred, in fractional currency unit (e.g. cents).
currency	String	“USD”	Currency in which these funds were transferred.
related_bags	List of Integers	[12345, 12346, 18283]	Violet Bag IDs for which this transfer was processed.
related_orders	List of Integers	[22345, 22346, 28283]	Violet Order IDs for which this transfer was processed.
related_distributions	List of Integers	[1118941, 1231123, 181283]	Violet Distribution IDs for which this transfer was processed. The Distributions are the specific amounts for each Bag that were owed to this merchant.
errors	List of Strings	[”Funds cannot be transferred to an account located in India unless service agreement type is recipient”]	For a failed transfer, this field provides detailed error information from either Violet or Stripe, explaining the cause of the failure.