Transfer API

The Transfer API endpoints let you create, retrieve, and manage individual payouts and transfer batches. Understanding the response fields—especially ach_trace_id—helps you trace ACH transfers through the payment rail and handle backward compatibility.

Transfer Response Fields

Transfer API v2 responses include fields for tracking payouts and their status. The ach_trace_id field is the canonical identifier for tracing ACH transfers.

ACH Trace ID

ach_trace_id is the primary field name for ACH transfer tracing in Transfer API v2 responses. This field contains the trace identifier returned by the payment rail provider, which you can use to track the transfer through the banking network.

For backward compatibility, responses may also include payout_trace_id as an alias. The API returns ach_trace_id preferentially, falling back to payout_trace_id when the legacy field is present in stored transfer data.

Field	Type	Description
`ach_trace_id`	string or null	Canonical ACH trace identifier for the transfer
`payout_trace_id`	string or null	Legacy alias for `ach_trace_id`; retained for backward compatibility

Use ach_trace_id as the authoritative field in new integrations. If you're working with existing data, check both fields—the API returns whichever is available.

Example Transfer Response

{
  "id": "tra_abc123",
  "status": "completed",
  "amount": 2500,
  "user_id": "usr_xyz789",
  "ach_trace_id": "ACH-TRACE-12345",
  "created_at": "2024-01-15T10:30:00Z"
}

For help troubleshooting transfer failures, see Where is my money?.

Transfer Batches

Transfer batches let you create multiple transfers in a single API call. Each batch is owned by the API app that created it, and ownership is enforced on retrieval.

Batch Ownership Validation

GET /v2/transfer-batches/:id requires ownership validation:

Only the API app that created a batch can retrieve it
Cross-app requests return 404 with the error: Transfer batch not found
This prevents apps from accessing batches created by other apps in the same organization

TransferBatch Response Fields

The TransferBatch.to_api_dict_v2() response includes:

Field	Type	Description
`id`	string	Batch identifier
`status`	string	Batch status: `pending` or `completed`
`items`	array	Array of TransferBatchItem objects
`metadata`	object	Custom metadata attached to the batch

TransferBatchItem Response Fields

Each item in the items array includes:

Field	Type	Description
`transfer_id`	string	Transfer identifier
`amount`	number	Transfer amount in cents
`user_id`	string	Recipient user ID
`tax_exempt`	boolean	Whether the transfer is tax-exempt
`allow_debit`	boolean	Whether debit is allowed
`metadata`	object	Custom metadata for this transfer
`error`	string or null	Error message if the transfer failed

Example Batch Response

{
  "id": "tb_abc123",
  "status": "completed",
  "items": [
    {
      "transfer_id": "tra_xyz789",
      "amount": 1000,
      "user_id": "usr_001",
      "tax_exempt": false,
      "allow_debit": true,
      "metadata": {},
      "error": null
    },
    {
      "transfer_id": "tra_def456",
      "amount": 2500,
      "user_id": "usr_002",
      "tax_exempt": false,
      "allow_debit": false,
      "metadata": {"ref": "payout-2024-01"},
      "error": null
    }
  ],
  "metadata": {
    "batch_name": "January payouts"
  }
}

Error Handling

404 Transfer Batch Not Found

If you receive 404 with Transfer batch not found when calling GET /v2/transfer-batches/:id:

Verify the batch was created by the same API app you're using to retrieve it
Cross-app access is not permitted, even within the same organization
Check that you're using the correct batch ID and API credentials

For app management endpoints, see App Management API.

Transfer Providers

Dots routes transfers through multiple backend providers—including GrailPay, BVNK, and GiBank—to optimize for speed, reliability, and cost. The provider selection happens automatically based on your transfer configuration and is not visible in the API response.

All providers map to the same normalized transfer statuses (created, pending, completed, failed, canceled). You interact with transfers the same way regardless of which backend provider processes them.

ACH trace IDs are now visible in the Transfer details view in the Dots dashboard for completed ACH transfers. You can use the trace ID to coordinate with your bank or Dots support when investigating transfer status.

What this means for you

The ach_trace_id field remains the canonical identifier for tracing ACH and RTP transfers through the payment rail.
Transfer status workflows are unchanged—use the same status checks, webhooks, and troubleshooting steps.
When contacting support about a transfer, provide the transfer ID and amount; support can look up provider-specific details if needed.

For transfer status meanings and troubleshooting, see Where is my money?

Was this helpful?