External entity payments are a team-scoped operation. The signer must hold a wallet with payment permissions on the team’s RiseID, exactly like standard payments.
When to use this
Standard payments
Recipient is already a member of your team. Use
client.payments.* and POST /v2/payments.External entity payments
Recipient is an outside vendor/supplier identified by email. Use
client.billPay.* and the external_entity endpoints.Payment flow
External-entity instant payments follow the same secure prepare → sign → execute pattern as standard payments. The signature is produced locally with your wallet; the private key never leaves your process.1
Create or reference a recipient
Register the external recipient under the team (or reuse an existing one).
2
Prepare the payment
Request EIP-712 typed data for the instant payment.
3
Sign with your wallet
Sign the returned typed data locally.
4
Execute
Submit the signature to execute the payment on-chain.
SDK usage
Manage recipients
Send an instant payment (one call)
sendInstantPayment runs the full prepare → sign → execute flow for you. It needs a private key to sign — either passed inline or configured on the client via riseIdAuth.
Prepare and execute separately
If you sign with an external wallet (hardware wallet, custody service), split the flow:REST endpoints
See the API Reference for full request and response schemas.
Payment references and retries
External-entity instant payments do not accept anexternal_id. It is not part of the POST /v2/payments/external_entity/instant request body, and any value sent is ignored. The instant endpoints also do not take an x-idempotency-key header.
Before retrying a failed or timed-out execute, check whether the payment was already sent by listing the team’s external-entity payments (GET /v2/payments/teams/{team_nanoid}/external_entity/payments).
Related
- Payment Integration Guide — standard payments to team members
- Payments concept — payment flow and on-chain security
- Error Handling — handling
409and validation errors
