Process Transfers for a single Bag

As of October 8th 2025: Duplicate transfer requests now return a 409 Conflict error instead of a 2XX response with an empty result.

When attempting to process transfers for bags that have already had their distributions settled, the API returns the following error:

{
  "error": "transfer_already_processed",
  "error_code": "4461",
  "error_message": "All transfers for this entity have already been processed."
}

Process Transfers for a single Bag

post

Path parameters

order_idinteger · int64Required

bag_idinteger · int64Required

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

Responses

200

Process Transfers for a Bag

application/json

Record of Payout Transfer

idinteger · int64Read-onlyOptional

payment_transactioninteger · int64Optional

Unique identifier of the Payment Transaction that this Transfer is associated with.

payout_idinteger · int32Optional

ID of the Payout, if any, this Transfer is associated to

payment_provider_idstringOptional

ID of the transfer record in Stripe

payment_provider_payout_idstringOptional

External ID of the payout record

payout_account_idinteger · int32Optional

ID of the Payout Account this Transfer belongs to.

bag_amountinteger · int32Optional

Total value for the bag associated to this transfer

bag_currencystringOptional

Original currency that this bag was processed in.

amountinteger · int32Optional

Total amount in fractional currency unit (e.g. cents) for this transfer.

currencystringOptional

Currency that this transfer was processed in.

statusstring · enumOptional

Status of the transfer.

Possible values:

typestring · enumOptional

Account type of the Transfer recipient.

Possible values:

payment_providerstring · enumOptional

Payment Provider that this transfer is executed with. This is the provider that handles transfer processing for this payout account.

Possible values:

related_ordersstring[]Optional

Identifiers of the Orders in Violet that are associated with this transfer.

related_bagsstring[]Optional

Identifiers of the Bags in Violet that are associated with this transfer.

related_distributionsstring[]Optional

Identifiers of the Distributions in Violet that are associated with this transfer. The amount of this Transfer is directly computed as the sum of all Distributions related to it.

transfer_reversalsstring[]Optional

Unique identifiers of the Transfer Reversal objects in Violet that are associated with this transfer.

idempotency_keystringOptional

Unique key to prevent duplicate transfers. This is generated by the Violet and unique for each transfer being processed.

transfer_mechanismstring · enumOptional

Mechanism used to execute this transfer. STANDARD_TRANSFERS uses /v1/transfers API, DESTINATION_PAYMENTS uses Payment Intent with transfer_data.destination. This is stored at creation time to prevent configuration race conditions.

Possible values:

date_createdstring · date-timeOptional

Time at which the object was created. In ISO-8601 format.

date_last_modifiedstring · date-timeOptional

Time at which the object was last modified. In ISO-8601 format.

payoutExternalIdstringOptional

paymentServicestring · enumOptionalPossible values:

externalIdstringOptional

post

/orders/{order_id}/bags/{bag_id}/transfer_funds

HTTPcURLJavaScriptPython

POST /v1/orders/{order_id}/bags/{bag_id}/transfer_funds HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Accept: */*

200

Process Transfers for a Bag

{
  "id": 93558,
  "payment_provider_id": "tr_1QNJyxKUtPkD6xdUIfdcyt8I",
  "payout_account_id": 1025,
  "amount": 180000,
  "currency": "USD",
  "status": "SENT",
  "payment_provider": "EXTERNAL",
  "related_orders": [
    "149394"
  ],
  "related_bags": [
    "139862"
  ],
  "date_created": "2024-11-20T19:54:35+0000",
  "date_last_modified": "2024-11-20T19:54:35+0000",
  "errors": [],
  "payment_service": "EXTERNAL",
  "external_id": "tr_1QNJyxKUtPkD6xdUIfdcyt8I"
}