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.
Optional payment purpose/description.
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. Where the transfer is authorized, testnet USDC is broadcast shortly after this responds and the destination balance is credited a few seconds later; a rejected transfer moves no money. Use POST /v1/payments/simulate-inbound to simulate a credited deposit without a travel-rule exchange. 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_statusForces the risk_status of the screening that runs once the simulated money arrives. Omitted, the inbound is screened for real. Only meaningful on the authorized branch — a rejected transfer sends no money and is never screened.
Simulate an inbound travel-rule exchange with a counterparty VASP (non-production only) › Responses
The compliance round trip finished and the inbound payment exists. This is not by itself a sign the transfer was authorized — a REJECTED transfer also produces a payment here, one whose step is failed rather than pending. Read the decision from GET /v1/payments/{id}: provider_metadata carries the Notabene transfer and its status, and participants carries the name match. Where the transfer was authorized, testnet USDC is broadcast just after this response and the payment confirms and credits a few seconds later, which payment.updated announces.
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.
Optional payment purpose/description.
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