Using External Transfers

External transfers provide flexibility in managing payment flows between Violet, channels, and merchants. This feature allows you to process payment capture through Violet, leverage our bookkeeping features such as Distributions, however, process Transfers to merchants independently to Violet. You can then register these Transfers in our system via API for bookkeeping.

With EXTERNAL Transfers, you can:

• Leverage Violet's bookkeeping features such as Distributions and Transfers

• Batch transfers for multiple orders or time periods

• Process Transfers independently to Violet, such as through direct Bank Transfers.

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

1

Configuring your app

To use EXTERNAL 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 EXTERNAL transfers. This is also available at the merchant level, so that specific merchants can be configured for EXTERNAL transfers, while others are on AUTOMATIC 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": "CAPTURED",
            "capture_method": "AUTOMATIC",
            "transfer_status": "PENDING",
            "transfer_method": "EXTERNAL",
            "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

Determining outstanding funds for a Merchant

You are required to process Transfers to Merchants independently from Violet's tooling. This could be using a method such as a direct Bank Transfer, or a different third-party payment provider.

To ensure you're able to easily track how much funds are outstanding for a given merchant, you can use the following API:

GET /v1/payments/transfers/pending?merchant_id=10092

// Sample Response
[
    {
        "merchant_id": 10092,
        "amount": 123900,
        "currency": "GBP",
        "related_distributions": [
            100011,
            100012,
            100092
        ]
    }
]

This will return a list of all pending transfers for a given merchant, including the amount, currency, and any related Distributions. You can then use this information to process the transfer to the merchant. It is important to know which Distributions contribute to the pending amount, because you will manually be required to mark these Distributions as SENT via to ensure they are excluded from future accounting.

4

Processing transfers to Merchants

You are required to process Transfers to Merchants independently from Violet's tooling. This could be using a method such as a direct Bank Transfer, or a different third-party payment provider.

5

Register the Transfer with Violet

Use the following API to register the Transfer you processed with Violet. This is important to do to ensure that any associated Distributions are marked as SENT.

POST v1/payments/transfers/register

{
    "merchant_id": 12345
    "payment_provider": "Western Union"
    "payment_provider_id": "wz_789xyz"
    "related_distributions": [
        100011,
        100012,
        100092
    ]
    "metadata": {
        "transfer_payment_method": "SWIFT",
        "bank_transfer_id": "by_1234567"
        ...
    }
}

// Sample Response
{
    "transfer_id": "abc123",
    "merchant_id": 12345,
    "payment_provider": "WESTERN_UNION", /
    "payment_provider_id": "wz_789xyz",
    "successful_distributions": [
        "10012",
        ...
    ],
    "failed_distributions": [
        "10032",
        ...
    ],
    "date_created": "2025-02-26T14:30:00Z",
    "metadata": {
        "transfer_payment_method": "SWIFT",
        "bank_transfer_id": "asdfghjkl"
    },
    "error_details": [
        {
            "distribution_id": 10032,
            "reason": "Distribution was already marked as SENT".
        },
        {
            "distribution_id": 1009000,
            "reason": "Distribution does not exist".
        }
    ]
}

If registered successfully, Violet will persist a Transfer object to reflect the external transfer and respond with the custom response above, which includes details of any failures.

Understanding the Transfer Object

The Transfer object represents a payment transfer 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.

Since you are processing EXTERNAL Transfers, this record in Violet is for bookkeeping and ensures that there is an association between a Transfer of funds and any generated Distributions. It is generated from the data passed in to the Register Transfer API.

Sample Transfer

Field	Type	Sample Value	Notes
merchant_id	Integer	12345	The unique identifier of the merchant that this transfer is associated with.
payment_provider_transfer_id	String	“wz_789xyz”	The unique identifier of the Transfer object in your payment provider.
status	String	SUCCESS , FAILED	Denotes what state the transfer is in. When associated to an EXTERNAL Transfer, this status is always SUCCESS
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.