Simulate Transfer Status
Move a Sandbox transfer through its statuses without a real payment.
In Sandbox, events such as a wire arriving or a payout settling don't happen on their own. Use these endpoints to move a transfer to its next status.
Status Flow
How a transfer moves between statuses, and where each Sandbox call applies.
%%{init: {"flowchart": {"curve": "monotoneY"}, "state": {"curve": "monotoneY", "useMaxWidth": false}}}%%
stateDiagram-v2
state "simulate-paid" as paid
state "simulate-settled" as settled
state "simulate-completed" as payout
[*] --> pending_customer_transfer_start: On-ramp
[*] --> pending_harbor: Off-ramp, swap
pending_customer_transfer_start --> paid: Wire, RTP, ACH Push
paid --> pending_harbor
pending_customer_transfer_start --> awaiting_settlement: ACH Pull, Debit Card
awaiting_settlement --> settled: ACH Pull
settled --> pending_harbor
awaiting_settlement --> pending_harbor: Debit Card, automatic
pending_harbor --> payout
payout --> completed
classDef success fill:#d1fae5,stroke:#059669,color:#065f46
class completed success
classDef warning fill:#fef3c7,stroke:#d97706,color:#92400e
class awaiting_settlement warning
classDef step fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray:4 4,color:#4b5563
class paid, settled, payout stepSupported Transfers
Each call works for some transfers. For the others, Sandbox runs the step itself, or you send a real deposit.
On-ramp
| Payment method | simulate-paid | simulate-settled | simulate-completed |
|---|---|---|---|
DOMESTIC_WIRE, RTP, ACH_PUSH | Yes | No | Yes |
ACH_PULL | No, automatic | Yes | Yes |
DEBIT_CARD | No, automatic | No, automatic | Yes |
Off-ramp
Send real testnet USDC with the Testnet Faucet. The transfer then moves to pending_harbor. Call simulate-completed.
On-chain
Send real testnet USDC with the Testnet Faucet. The transfer then moves to pending_harbor. Call simulate-completed.
Simulate the Payment
The Customer's payment arrived. The transfer moves from pending_customer_transfer_start to pending_harbor.
POST /api/v1/transfers/{transfer_uuid}/simulate-paid
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/transfers/{{TRANSFER_UUID}}/simulate-paid' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}'If it fails, the transfer is usually not in pending_customer_transfer_start. Transfer is not in pending_customer_transfer_start state. and Order status is not unpaid mean the payment was already simulated. Call /simulate-completed.
Simulate the Settlement
After the funds are pulled, ACH_PULL and DEBIT_CARD on-ramp transfers wait for the bank to settle. The status stays pending_customer_transfer_start, and the sub_status is awaiting_settlement. Harbor also sends the transfer.sub_status.awaiting_settlement webhook.
POST /api/v1/transfers/{transfer_uuid}/simulate-settled
DEBIT_CARD: Sandbox settles automatically. The transfer moves topending_harborwithin a few minutes.ACH_PULL: settlement can take hours or days, as on a real bank network. Call this endpoint to skip the wait.
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/transfers/{{TRANSFER_UUID}}/simulate-settled' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}'{
"message": "The transfer status was updated successfully.",
"data": null
}If the transfer isn't waiting for settlement, the request returns 400 with error code 3011 and the message Transfer is not in awaiting_settlement state.
Simulate the Payout
Harbor paid the final destination, a bank or a blockchain address. The transfer moves from pending_harbor to completed. This works for all transfer types.
POST /api/v1/transfers/{transfer_uuid}/simulate-completed
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/transfers/{{TRANSFER_UUID}}/simulate-completed' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}'If it fails, the transfer isn't pending_harbor yet. Transfer is not in pending_harbor state. and Order status is not paid mean the payment wasn't simulated. For DOMESTIC_WIRE, RTP and ACH_PUSH, call /simulate-paid first. Order status is not in_process means the transfer already completed or expired.
Notes
- In Production, the calls return
This endpoint is not available in production. - For settlement times in Production, see Payment Lock Time.
Updated about 1 month ago