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:

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.

Last updated

Was this helpful?