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

Initiates a payout transfer for a specific bag within an order. The order is validated for existence and the caller's access is verified before processing. Returns a single PayoutTransfer object representing the transfer result for the specified bag, including the transfer status, amount, payment provider details, and any errors encountered.

Path parameters

order_idinteger · int64Required

ID of the order containing the bag

Example: 11111

bag_idinteger · int64Required

ID of the bag to process the transfer for

Example: 22222

Header parameters

X-Violet-TokenstringRequired

API token for authentication

X-Violet-App-SecretstringRequired

Application secret key

X-Violet-App-Idinteger · int32Required

Application ID

Example: 10000

Responses

200

ok

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:

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.

externalIdstringOptional

payoutExternalIdstringOptional

paymentServicestring · enumOptionalPossible values:

effectiveRelatedOrderIdsinteger · int64[]Optional

effectiveRelatedBagIdsinteger · int64[]Optional

effectiveRelatedDistributionIdsinteger · int64[]Optional

effectiveTransferReversalIdsinteger · int64[]Optional

related_ordersstring[]OptionalDeprecated

DEPRECATED: Use related_order_ids instead. Identifiers of the Orders in Violet that are associated with this transfer.

related_bagsstring[]OptionalDeprecated

DEPRECATED: Use related_bag_ids instead. Identifiers of the Bags in Violet that are associated with this transfer.

related_distributionsstring[]OptionalDeprecated

DEPRECATED: Use related_distribution_ids instead. Identifiers of the Distributions in Violet that are associated with this transfer.

transfer_reversalsstring[]OptionalDeprecated

DEPRECATED: Use transfer_reversal_ids instead. Unique identifiers of the Transfer Reversal objects in Violet that are associated with this transfer.

related_order_idsinteger · int64[]Optional

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

related_bag_idsinteger · int64[]Optional

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

related_distribution_idsinteger · int64[]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_reversal_idsinteger · int64[]Optional

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

403

forbidden

application/json

404

not found

application/json

500

internal server error

application/json

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: */*

{
  "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"
}