Payments
Get payments
Retrieve all payments for the authenticated user's organization.
query Parameters
start_dateStart date for filtering payments (ISO 8601 format)
end_dateEnd date for filtering payments (ISO 8601 format)
directionPayment direction filter: 'outbound' for outgoing payments, 'inbound' for incoming payments
pagePage number for pagination (1-based)
limitNumber of items per page (default: 20)
Get payments › Responses
Successfully retrieved team payments
Create payment
Create a payment. Returns the created payment details.
Create payment › Request Body
Caller's stated intent for the payment.
organization_reference_idOptional external reference ID for tracking.
funding_account_idFunding account ID. Optional at POST to support the two-step PATCH creation flow; required together with desired.from.account_id and desired.to.account_id once any of the three is supplied.
Create payment › Responses
Payment created successfully
Payment data
Simulate an inbound payment with a chosen risk status (non-production only)
Sends a real on-chain test-USDC transfer from the platform faucet into a managed wallet and forces the risk-screening verdict to mocked_risk_status. Not available in production. Returns 201 with the screened payment, or 202 with the tx hash if it is still being detected/screened.
Simulate an inbound payment with a chosen risk status (non-production only) › Request Body
to_account^([0-9a-fA-F]{8}-[0-… · requiredManaged account ID that should receive the simulated inbound.
mocked_risk_statusThe risk_status the screening verdict should be forced to.
networkEVM testnet to send on. Defaults to BASE_SEPOLIA.
Simulate an inbound payment with a chosen risk status (non-production only) › Responses
The simulated inbound payment, already screened to mocked_risk_status.
Payment data
Simulate an inbound travel-rule exchange with a counterparty VASP (non-production only)
Has a Tesser-operated simulator VASP originate a real Notabene travel-rule transfer into one of your managed wallets, so you can rehearse your travel-rule handling without a second VASP. This simulates the travel-rule exchange, not the money: nothing is sent on chain and no balance changes. Use POST /v1/payments/simulate-inbound to simulate a credited deposit. Not available in production.
Simulate an inbound travel-rule exchange with a counterparty VASP (non-production only) › Request Body
to_account^([0-9a-fA-F]{8}-[0-… · requiredManaged account ID the simulated counterparty should claim to be paying.
claimed_beneficiary_nameName the simulated counterparty claims for the beneficiary. Omitted, it claims the destination owner's own name and the transfer is authorized; supplied and wrong, name matching refuses it.
networkEVM testnet the simulated transfer settles on. Defaults to BASE_SEPOLIA.
mocked_risk_statusNot supported here: this endpoint simulates the travel-rule exchange, not the money. Use POST /v1/payments/simulate-inbound to rehearse a risk verdict.
Simulate an inbound travel-rule exchange with a counterparty VASP (non-production only) › Responses
The compliance round trip finished and the inbound payment exists. Read travel_rule.status for the decision itself: a REJECTED transfer also produces a payment here, one whose step is failed rather than pending, so this response is not by itself a sign the transfer was authorized. The payment's pending step stays created and carries the fabricated settlement hash once Notabene's settlement webhook arrives, which is usually just after this response — no money was sent. settlement_id is null if the simulated settlement itself did not go through.
Update payment
Update a payment with accounts.
path Parameters
paymentIdUnique identifier of the payment to update
Update payment › Request Body
funding_account_idFunding account ID for the payment.
Account IDs to attach to the payment.
organization_reference_idOptional external reference ID for tracking.
Update payment › Responses
Payment updated successfully
Payment data
Submit risk review
Manually review and approve or reject a payment requiring risk review.
path Parameters
paymentIdUnique identifier of the payment to review
Submit risk review › Request Body
is_approvedApprove (true) or reject (false) the payment.
Submit risk review › Responses
Payment review completed successfully
Payment data
Sign payment step
Submit a signature for a self-custodial payment step. Webhook updates will be sent as the signature is validated and submitted onchain.
path Parameters
paymentIdUnique identifier of the payment
stepIdUnique identifier of the payment step to sign
Sign payment step › Request Body
signatureBase64-encoded JSON envelope { body, stamp } where body is the JSON-encoded Turnkey ACTIVITY_TYPE_SIGN_TRANSACTION_V2 activity and stamp is the X-Stamp header value produced by stamping that body. Wire format: base64(JSON.stringify({ body, stamp })).
Sign payment step › Responses
Signature accepted. In turn: the step is confirmed with its broadcast transaction_hash; completed follows finality. Queued behind an earlier nonce from the same wallet: the step is signed with transaction_hash null until it broadcasts.
Payment data