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.

CUSTOM Transfers are currently limited to accounts using EXTERNAL or CUSTOM payments. Learn more about Violet’s Flexible Payment and Transfer Strategies

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:

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"
}
FieldTypeSample ValueNotes
merchant_idInteger12345The unique identifier of the merchant that this transfer is associated with.
payout_account_idInteger99999The unique identifier of the Violet payout account for the merchant that this transfer was sent to.
payment_provider_transfer_idString“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.
statusStringSUCCESS , FAILEDDenotes 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.
amountInteger10000Amount transferred, in fractional currency unit (e.g. cents).
currencyString“USD”Currency in which these funds were transferred.
related_bagsList of Integers[12345, 12346, 18283]Violet Bag IDs for which this transfer was processed.
related_ordersList of Integers[22345, 22346, 28283]Violet Order IDs for which this transfer was processed.
related_distributionsList 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.
errorsList 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.

Was this page helpful?

Payment TransactionsSupported Currencies