Refunds and Returns¶

When an investor withdraws, the investment is canceled and, if funds have already reached escrow, returned to the investor. Escrow accounts are overseen manually under the terms of the escrow agreement, so returns are requested through TransactAPI and processed by North Capital's escrow team. Use this step when you need to cancel a trade, void a pending payment, or return funds to an investor.

Before You Start¶

The trade exists and you have its tradeId. See Create the Trade.
Webhooks are registered for cancelInvestment and updateTradeStatus, so you are notified as the trade moves to its final status. See Register Webhooks.
You understand the trade statuses described in Settle and Manage.

What cancelInvestment Does¶

cancelInvestment works out the right action from the trade's status and, for ACH and credit card trades, the status of its payment:

Trade status	Payment status	Result
`CREATED`	No ACH or card payment, or payment `Returned`, `Voided`, or `Declined`	The trade is canceled and moves to `CANCELED`.
`CREATED`	`Pending`	The payment is voided and the trade moves to `CANCELED`.
`CREATED`	`Submitted`	The cancellation is queued. If the payment settles, the trade moves to `UNWIND PENDING` and a return is requested. If the payment is returned, voided, or declined, the queued cancellation is dropped.
`CREATED`	`Settled`	The trade moves to `UNWIND PENDING` and a return is requested.
`FUNDED`	Any	The trade moves to `UNWIND PENDING` and a return is requested.

When North Capital's escrow team has processed a return, the trade moves to UNWIND SETTLED.

Steps¶

1. Cancel the investment¶

Call cancelInvestment with the trade and the reason for the cancellation. tradeId, requestedBy, and reason are required; notes is optional.

curl -X POST "$TAPI_HOST/v3/cancelInvestment" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d tradeId=123456 \
  -d "requestedBy=Jane Doe" \
  -d "reason=Investor withdrew" \
  -d "notes=Requested by email"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "Canceled investment details": [
    {
      "offeringId": "12345",
      "accountId": "A12345",
      "partyId": "P12345",
      "orderId": "123456",
      "transactionType": "WIRE",
      "totalAmount": "12345.000000",
      "orderStatus": "UNWIND PENDING"
    }
  ]
}

orderStatus in Canceled investment details is the trade's status after the call: CANCELED when the trade was canceled outright, UNWIND PENDING when a return was requested, or unchanged when the cancellation was queued. See POST /v3/cancelInvestment.

2. Track the return¶

When a return has been requested, watch for the updateTradeStatus webhook that moves the trade to UNWIND SETTLED, or read the trade to check its status.

curl -X GET "$TAPI_HOST/v3/trades?filter[tradeId]=123456" \
  --globoff \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "trades": [
    {
      "tradeId": "123456",
      "accountId": "A12345",
      "offeringId": "12345",
      "tradeStatus": "UNWIND SETTLED"
    }
  ],
  "pagination": {
    "totalRecords": 1,
    "startIndex": 0,
    "endIndex": 0
  }
}

tradeStatus is UNWIND SETTLED once the funds have been returned to the investor.

Voiding a Pending Payment¶

cancelInvestment voids a Pending ACH or card payment for you. To void a payment without canceling the trade, for example to retry with a different bank account, call requestForVoidACH or requestForVoidCCTransaction with the payment's RefNum. Only Pending payments can be voided; pending payments are submitted for processing at 6:00 PM Eastern Time each business day.

curl -X POST "$TAPI_HOST/v3/requestForVoidACH" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d RefNum=12345

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "investorExternalAccountDetails": "Status Updated Successfully"
}

The payment's fundStatus becomes Voided. See POST /v3/requestForVoidACH and POST /v3/requestForVoidCCTransaction.

Returns Without an Integration¶

If returns are rare on your platform, you can request them in the Transact Portal instead of building an integration. Open the funded trade under Trades, select Request Return, and submit the request.

fundReturnRequest is a legacy method that records a return request without changing the trade's status. Use cancelInvestment instead.

Webhooks¶

cancelInvestment fires when the call completes, with the trade's resulting OrderStatus.
updateTradeStatus fires when the trade moves to UNWIND PENDING, CANCELED, or UNWIND SETTLED.
deleteTrade fires when a CREATED trade is canceled.
requestForVoidACH and requestForVoidCCTransaction fire when a pending payment is voided, including voids made by cancelInvestment.

See Trades, ACH and External Accounts, and Credit Card in the Webhooks method reference for the payload fields.

Common Errors¶

Code	When it happens here
`106`	`tradeId`, `requestedBy`, or `reason` is missing.
`749`	The `tradeId` sent to `cancelInvestment` does not exist.
`189`	A return has already been requested for this trade (`Return already requested`).
`770`	`deleteTrade` was called on a credit card trade whose payment is `Pending` or `Submitted`. Use `cancelInvestment`, which voids or queues the payment first.
`224`	The payment is no longer `Pending` and cannot be voided.

See Error Codes for the full list.

Next¶

Continue to 8. Go Live.