Statuses

Every institution on a transfer keeps its own state, and no state is shared between them. Two statuses matter most: your own, My Status in the dashboard, and the transaction status, Tx Status, which combines every institution’s status with the settlement. It is normal for the two to differ while a transfer is in progress.

My Status and Transaction status, together

Read the two together to know where a transfer stands and whether it waits on you.

Your status (My Status)

Your status says where your institution stands on the transfer. It is public, so every institution on the transfer sees the status of every other one, but not why. In the API, it is the status of your own entry in the transfer’s agents, the one with your DID and the role VASP. The other entries in agents, such as the settlement address, do not count towards any status.

Your status can still change after it is Authorized. When something on the transfer changes and your policies run again, a new flag or a reopened requirement puts it back to Pending, and a rejection makes it Rejected. When your team overrides a flag with POST /api/v1/transfers/{id}/force-authorize, it becomes Authorized straight away and every open requirement your institution set becomes Skipped. Requirements another institution set for you stay open until you meet them, and the hold on personal data is never skipped.

Transaction status

The transaction status says where the transfer stands across every institution. It is the status of the transfer itself, which Notabene derives from every institution’s status and the settlement. When an institution has canceled, the transfer is Canceled even if another one rejected it.

Once a transfer is settled, it never returns to a status before settlement. Settled can still move back to SettledIncompleteAuthorization, for example when an institution rejects the transfer after settlement over a compliance issue, and returning the funds then takes a revert.

Each time the transaction status changes, your webhook endpoint receives transfer.status_changed.v3 with the status before and after. When your policies hold the transfer for review, the transfer reads requires_action: true until your team decides. Webhooks describes the other events.

{
  "eventType": "transfer.status_changed.v3",
  "payload": {
    "id": "8f3c2a1e-5b7d-4c90-a1f2-3e4d5c6b7a80",
    "for": "did:web:example.com:pt",
    "fromStatus": "ReadyToSettle",
    "toStatus": "Settled",
    "settlementId": "eip155:1:tx/0x7d3c9e1f0a2b4c6d8e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d"
  }
}

{
  "eventType": "transfer.status_changed.v3",
  "payload": {
    "id": "8f3c2a1e-5b7d-4c90-a1f2-3e4d5c6b7a80",
    "for": "did:web:example.com:pt",
    "fromStatus": "ReadyToSettle",
    "toStatus": "Settled",
    "settlementId": "eip155:1:tx/0x7d3c9e1f0a2b4c6d8e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d"
  }
}

Reverts

To return the funds of a settled transfer, request a revert with POST /api/v1/transfers/{id}/revert and a reason, which is shared with the counterparty. The revert is a new transfer linked to the original, and the funds go back to the original source_address or to the settlement_address you give. The counterparty authorizes it like any other transfer, and the original transfer’s status follows it.

Other statuses on a transfer

Under the two main statuses, three more say what is still open and why.

Pending appears three times: your status waits on your side, a requirement waits on the institution that must meet it, and your send status waits on the counterparty.

Requirement statuses

A requirement is something that must happen before an institution can be authorized, such as receiving the Travel Rule data or confirming a deposit address. Every requirement has an institution that sets it and an institution that must satisfy it, and each has its own status.

In the API, a requirement’s status reads Pending, Satisfied, Skipped or Rejected. The values for Partially satisfied and N/A are still to be published. (placeholder)

Only the institution that set a requirement can skip or reject it, and every skip is recorded in your audit trail, whatever its cause.

Your policies’ verdict

Your policies give each transfer a verdict: approve, flag or reject. Because the verdict is private, the other institutions only see its effect on your status, and a flag keeps that status Pending until a person on your team decides. Your audit trail records it as transaction.compliance.evaluated events whose details.decision is Authorize, Flag or Reject.

Your send status

Your send status, which only you see, says whether your Travel Rule data has reached each counterparty: Sent, or Pending while the counterparty cannot receive it. Sending happens in two steps: the transfer details go first, and your customer’s personal data is held until the counterparty confirms that the destination address belongs to its customer. A counterparty still on Transact v1 receives all the data in the first message.

The hold on personal data cannot be skipped, so a transfer can be Authorized while no personal data has been sent yet. Sending and authorizing are independent, and your status does not wait for your data to be sent unless you turned on the requirement to transmit Travel Rule data.

Statuses on other records