Ospree docs
API ReferenceWebsiteSocials
  • GETTING STARTED
    • Intro to Ospree
      • What is the Travel Rule?
      • Types of Travel Rule transfers
      • What is a wallet address?
      • What is an Account at Ospree?
      • What is a VASP or CASP?
    • Account
      • Understand user roles
      • Add and manage users
      • Change your password
      • Set up two-factor authentication (2FA)
      • Log in with 2FA-enabled
  • DASHBOARD
    • Overview
    • Travel Rule
      • Start a transfer
      • Search and filter transfers
      • Interoperability
      • Self-hosted wallets
    • Accounts Directory
      • Create an account
      • Edit an account
      • Create a recipient
      • Edit a recipient
      • Add a new wallet
      • VASPs
        • Search and filter
        • Request a VASP
  • OSPREE API
    • Overview
    • API integration flows
    • Authentication
    • Breaking Changes
    • Errors
    • Token Identifier
    • Webhooks
      • Webhook events
      • Webhook request
      • Webhook management
    • Travel Rule
      • Create Transfer
      • List Transfers
      • Retrieve Transfer
      • Update Transfer
      • Action Transfer
    • Accounts Directory
      • Create Account
      • List Accounts
      • Retrieve Account
      • Update Account
      • Remove account
      • Search account
      • Retrieve VASP
      • Search VASP
      • List VASPs
    • Blockchain Analytics
      • Create Address
      • List Addresses
      • Retrieve Address
      • Assign an address to account
      • Create Transaction (Beta)
      • List Transactions (Beta)
      • Retrieve Transaction (Beta)
  • Resources and Help
    • Data pre-validation
    • Sunrise Issue
Powered by GitBook
On this page
  1. OSPREE API
  2. Travel Rule

Action Transfer

PATCH /api/v2/travelrule/transfers/{transfer_id}/{action}

This endpoint is used to change the status of a transfer.

Path Parameters

Name
Type
Description
Required

transfer_id

string

The ID of the transfer. Example: 0663cc41-ef29-7995-8000-2d9b414b3174

True

action

string

The action to be applied. See list of supported actions below.

True

Request Body

Name
Type
Description
Required

retry

boolean

Indicates if transfer request should be updated for resending.

True if action is "reject"

reject_error

string

The rejection error code of the transfer request. See below for the list of error codes.

True if action is "reject"

message

string

Additional information on why transfer request is rejected.

True if action is "reject"

transaction_hash

string

The blockchain transaction hash of the completed crypto transaction.

True if action is "complete"

Transfer Status and Supported Actions

The allowed transfer actions depend on the protocol used and whether the transfer is outgoing or incoming. An outgoing transfer is initiated by the VASP to send a transfer request to a counterparty, while an incoming transfer is a transfer request received by the counterparty VASP. Each action taken—such as “accept,” “reject,” or “complete”—triggers a change in the transfer’s status, ensuring that the workflow reflects the real-time state of the transaction.

Actions
Status
Description

-

initiated

The transfer request is sent to the beneficiary VASP using the Create Transfer endpoint.

-

review

The transfer request is being reviewed by the beneficiary VASP.

cancel

canceled

The originator VASP canceled the transfer request using the Action Transfer endpoint.

repair

review

The originator VASP updates the transfer request based on the rejection reason using the Action Transfer endpoint.

reject

rejected

The beneficiary VASP rejected the originator VASP’s request, providing a reason and indicating whether a retry is allowed, using the Action Transfer endpoint.

accept

accepted

The beneficiary VASP accepted the transfer request, allowing the originator VASP to proceed with executing the crypto transaction using the Action Transfer endpoint.

complete

completed

The originator VASP has completed the execution of the crypto transaction using the Action Transfer endpoint.

Protocols
Outgoing Transfer (Action → Status)
Incoming Transfer (Action → Status)

flow

cancel → canceled repair → review complete → completed

accept → accepted reject → rejected

trisa

repair → review complete → completed

accept → accepted reject → rejected

trp

complete → completed

accept → accepted reject → rejected

Reject Error Codes
ID
Code
Description

0

REJECTED

Default rejection reason.

1

UNKNOWN_WALLET_ADDRESS

VASP doesn't control the beneficiary wallet address.

2

UNKNOWN_ORIGINATOR

VASP doesn't have KYC information for the beneficiary wallet address.

3

UNKNOWN_BENEFICIARY

The originator account can't be identified.

4

UNSUPPORTED_CURRENCY

The beneficiary account can't be identified.

5

EXCEEDED_TRADING_VOLUME

VASP can't receive more transaction inflows.

6

COMPLIANCE_CHECK_FAIL

VASP internal compliance check has failed.

7

NO_COMPLIANCE

VASP not able to implement travel rule compliance.

8

HIGH_RISK

VASP unwilling to proceed with the transaction after risk assessment.

9

OUT_OF_NETWORK

Wallet address or transaction is not available on the specified blockchain network.

10

BAD_REQUEST

11

UNPARSEABLE_IDENTITY

Unable to parse identity record.

12

PRIVATE_INFO_WRONG_FORMAT

13

UNPARSEABLE_TRANSACTION

Unable to parse transaction data record.

14

MISSING_FIELDS

There are missing required fields in the transaction data.

15

INCOMPLETE_IDENTITY

The identity record is not complete enough for compliance purposes.

16

VALIDATION_ERROR

There was an error validating a field in the transaction data.

17

COMPLIANCE_PERIOD_EXCEEDED

The review period has exceeded the required compliance timeline.

18

CANCELED

The transfer request was canceled.

Understanding Travel Rule Transfer Statuses

The status of a Travel Rule transfer evolves as the transfer progresses through different stages. Importantly, the status can differ depending on the point of view:

Originator’s View - The sender (originator) sees the status reflecting the current action they have completed or are awaiting confirmation on. Beneficiary’s View - The recipient (beneficiary) sees a status representing what is pending on their side, such as needing to review, accept, or reject the transfer.

This dual perspective ensures that each party clearly understands their respective responsibilities at any given stage.

"Rejected" with retry responses will be available in upcoming sprints.

VASP-to-VASP Withdrawal - Step-by-step

1. User → Originator VASP A: Initiates Withdrawal Request 2. Originator VASP A → Ospree: Create Travel Rule Transfer 3. Ospree → Beneficiary VASP B: Send Travel Rule Message 4. Beneficiary VASP B → Ospree: Respond. Action "accept" or "reject" 5. Ospree → Originator VASP A: Pass Beneficiary Response If "Accepted" 6a. Originator VASP A → Initiate Blockchain Transaction 6b. Originator VASP A → Ospree: Update Transfer respond action "complete" If “Rejected” without retry 6c. Originator VASP A → Customer: Notify Customer of Rejection 6d. Originator VASP A → End: Cancel Withdrawal If “Rejected” with retry 6e. Originator VASP A → Originator VASP A: Repair Travel Rule Data 6f. Originator VASP A → Ospree: Update Transfer. Action "repair" 6g. Ospree → Beneficiary VASP B: Re-send Updated Travel Rule Message 6h. Beneficiary VASP B → Ospree: Respond. Action “accept” 6i. Ospree → Originator VASP A: Forward New Response 6j. Originator VASP A → Initiate Blockchain Transaction 6k. Originator VASP A → Ospree: Update Transfer. Action "complete"

Response

{
  "status": "success",
  "data": {
    "transfer_id": "0663cc41-ef29-7995-8000-2d9b414b3174",
    "reference_id": "reference-transfer-01",
    "amount": 1,
    "amount_usd": 101234.00,
    "dti": "4H95J0R2X",
    "chain": "bitcoin",
    "symbol": "BTC",
    "protocol": "flow",
    "beneficiary_vasp_id": "ABCXYZ",
    "originator_address": "14qViLJfdGaP4EeHnDyJbEGQysnCpwk3gd",
    "beneficiary_address": "1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX",
    "originator_account_reference_id": "account5678",
    "beneficiary_account_reference_id": "account1234",
    "transaction_hash": "80003fee6bcbb2726b4d6466d690fce6caaa03771aada747eb0651637514b893",
    "transfer_status": "ACCEPTED"
  }
}

Last updated 11 days ago