Update Transfer

Overview

The Update Transfer API allows you to modify certain fields of an existing transfer for a business. This is typically used to update user-defined data or other modifiable fields after the transfer has been created. Note that not all fields can be updated once a transfer is in processing or completed status.

Resource Access

• HTTP Method: POST
• Endpoint: /v1/businesses/{business_id}/transfers/{transfer_id}
• Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
business_id	string (UUID)	Yes	Unique identifier for the business
transfer_id	string (UUID)	Yes	Unique identifier for the transfer to update

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication

Request Body

The request body should contain a JSON object with only the fields you want to update. Currently, only user_data can be updated after transfer creation.

{
  "user_data": {
    "derp": true,
    "reference": "Updated reference",
    "notes": "Additional notes"
  }
}

Request Fields

Field	Type	Required	Description
user_data	object	No	Updated additional user-defined data (optional)

Response

Success Response (200 OK)

{
  "id": "urn:uuid:transfer-123",
  "business_id": "urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc",
  "amount": {
    "currency": "USD",
    "amount": "1.00"
  },
  "bank_account_id": "urn:uuid:bank-account-123",
  "direction": "withdrawal",
  "type": "wire",
  "status": "pending",
  "idempotency_key": "urn:uuid:idempotency-123",
  "user_data": {
    "derp": true,
    "reference": "Updated reference",
    "notes": "Additional notes"
  },
  "created_at": "2022-01-01T00:00:00.000Z",
  "updated_at": "2022-01-01T12:00:00.000Z"
}

Response Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the transfer
business_id	string (UUID)	Business ID this transfer belongs to
amount	object	Transfer amount with currency
bank_account_id	string (UUID)	Bank account ID used for this transfer
direction	string	Transfer direction
type	string	Transfer method type
status	string	Current status of the transfer
idempotency_key	string (UUID)	Idempotency key used
user_data	object	Additional user-defined data
created_at	string (date-time)	Creation timestamp
updated_at	string (date-time)	Last update timestamp

Transfer Status Values

• pending: Transfer initiated but not yet processed
• processing: Transfer is being processed
• completed: Transfer successfully completed
• failed: Transfer failed to process
• cancelled: Transfer was cancelled

Transfer Direction Values

• deposit: Money coming into the business account
• withdrawal: Money going out of the business account

Transfer Type Values

• wire: Wire transfer (fastest, highest fees)
• ach: ACH transfer (slower, lower fees)
• check: Physical check (slowest, variable fees)

Error Responses

• 400 Bad Request: Invalid input data
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: User does not have permission to update this transfer
• 404 Not Found: Business or transfer not found
• 409 Conflict: Transfer cannot be updated in current status (e.g., already processing or completed)

Code Examples

cURL

curl -X POST \
  'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers/urn:uuid:transfer-123' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "user_data": {
      "derp": true,
      "reference": "Updated reference",
      "notes": "Additional notes"
    }
  }'

Python

import requests

url = "https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers/urn:uuid:transfer-123"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
data = {
    "user_data": {
        "derp": True,
        "reference": "Updated reference",
        "notes": "Additional notes"
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://api.example.com/v1/businesses/urn:uuid:9b397b0d-69bc-b09f-9d82-0e02637042fc/transfers/urn:uuid:transfer-123';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const data = {
  user_data: {
    derp: true,
    reference: 'Updated reference',
    notes: 'Additional notes'
  }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Only user_data can be updated after transfer creation
• Transfer must be in pending status to allow updates (cannot update processing or completed transfers)
• The authenticated user must have permission to modify transfers for the specified business
• Updates are partial - only provided fields will be modified
• The updated_at timestamp will be automatically updated when changes are made
• Use this API to add reference information, notes, or other metadata to existing transfers

Interactive API Explorer