Skip to main content
Direct is in early access. To request access, contact hi@natural.com.
A wire (wire_*) sends USD from a customer wallet to an external party account. The beneficiary needs a complete address. Account reachability is advisory. Natural checks account readiness when you create the wire. Create a wire with the customer wallet, external party account, amount, and description. You can include remittanceInfo for the beneficiary. Use an idempotency key so a retried request does not create another wire.

​
Lifecycle

A wire starts CREATED. Existing approval policies can place it in AWAITING_APPROVAL. Approval resumes submission. Denial ends it in APPROVAL_DENIED. After submission, the wire becomes PROCESSING. Settlement ends it in COMPLETED and sets completedAt. A bank rejection ends it in REJECTED. Other failures end it in FAILED. The failure field contains the available code and reason. Cancellation is available only before submission. A canceled wire ends in CANCELED. Wires have no RETURNED status. The event catalog describes wire.created, wire.processing, wire.completed, wire.rejected, and wire.failed. Events support both own-party subscriptions and delegated subscriptions with Direct read access.

​
Sandbox

Use the settle simulation and fail simulation to drive terminal states without waiting for bank processing.