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.

🚧

Sandbox Only

These endpoints are not available in Production.


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 step

Supported Transfers

Each call works for some transfers. For the others, Sandbox runs the step itself, or you send a real deposit.

On-ramp

Payment methodsimulate-paidsimulate-settledsimulate-completed
DOMESTIC_WIRE, RTP, ACH_PUSHYesNoYes
ACH_PULLNo, automaticYesYes
DEBIT_CARDNo, automaticNo, automaticYes

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 to pending_harbor within 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.

Did this page help you?