API Reference · Security & ownership
Ownership Transfers
Two-step ownership transfer initiation, acceptance, and cancellation. (Owner recovery has no API endpoint by design.)
The ownership_transfer object
Represents a ownership_transfer entity in the rafiqPay system.
| Field | Type & Flags | Description |
|---|---|---|
| id | string | Transfer ID (owt_...). |
| newOwnerUserId | string | Eligible team member ID. |
| status | enum | pending_acceptance | in_hold | completed | cancelled. |
Example ownership_transfer JSON
ownership_transfer example payload
{
"id": "owt_01",
"newOwnerUserId": "usr_ifeoma",
"status": "in_hold",
"holdEndsAt": "2026-10-23T14:00:00+01:00"
}Endpoints & Operations
POST/v1/ownership-transfersProposed
Start an ownership transfer
Requires an Owner-created key and the Owner twoStepCode.
Request Example
POST /v1/ownership-transfers
cURL · v1
curl -X POST "https://api.rafiqpay.net/v1/ownership-transfers" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
-H "Idempotency-Key: idem_start-ownership-transfer_01" \
-H "Content-Type: application/json" \
-d '{
"newOwnerUserId": "usr_ifeoma",
"twoStepCode": "482910"
}'Response (200 OK)
Response payload
{
"id": "owt_01",
"status": "pending_acceptance"
}POST/v1/ownership-transfers/:id/acceptProposed
Accept an ownership transfer
Called by the recipient using a key they created plus their twoStepCode.
Request Example
POST /v1/ownership-transfers/:id/accept
cURL · v1
curl -X POST "https://api.rafiqpay.net/v1/ownership-transfers/:id/accept" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
-H "Idempotency-Key: idem_accept-ownership-transfer_01" \
-H "Content-Type: application/json" \
-d '{
"twoStepCode": "918273"
}'Response (200 OK)
Response payload
{
"id": "owt_01",
"status": "in_hold"
}POST/v1/ownership-transfers/:id/cancelProposed
Cancel an ownership transfer
Cancels an in-flight ownership transfer before the hold expires.
Request Example
POST /v1/ownership-transfers/:id/cancel
cURL · v1
curl -X POST "https://api.rafiqpay.net/v1/ownership-transfers/:id/cancel" \
-H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
-H "Idempotency-Key: idem_cancel-ownership-transfer_01" \
-H "Content-Type: application/json" \
-d '{
"twoStepCode": "482910"
}'Response (200 OK)
Response payload
{
"id": "owt_01",
"status": "cancelled"
}Related Webhook Events
These events are dispatched to your webhook endpoints when actions occur on this resource: