Headless Transaction API
Walk through the full escrow lifecycle using the /api/partner/transactions/* endpoints. These are for partners building their own UI on top of XValuePay — no hosted checkout or embed involved. Requires your API key to have the portal:act_on_behalf_of scope.
Walkthrough state
Values extracted from each step's response and reused in subsequent calls.
sessionToken: —transactionUuid: —paymentUuid: —
1Create checkout session
Partner creates a checkout session server-side. In headless mode this seeds the transaction data but does not yet create the Transaction row.
POST/partner/checkout/sessions
2Initiate transaction (from session)
Use the standard /transactions/initiate endpoint with checkoutSessionToken. This creates the Transaction row (createdVia: "api") and links it to the session. In a full portal flow, the seller would accept first — headless mode lets the partner bypass that. Only transactions your key created this way can be driven through every step below: one the parties created in the checkout (createdVia: "portal") only allows get, payment-options, pay and confirm (the rest answer 403) unless VPay has granted your account headless checkout control. New partner accounts start under review: use a sandbox key here; live keys work once VPay approves the account.
POST/transactions/initiate
3Buyer: payment options (fee quote)
GET /api/partner/transactions/:uuid/payment-options — lists the payment methods available for this transaction with the exact amount the buyer pays and the seller receives for each. Use it to render your own payment step.
GET/partner/transactions/:uuid/payment-options
4Buyer: initiate payment (on behalf of)
POST /api/partner/transactions/:uuid/buyer/pay — requires scope portal:act_on_behalf_of. The partner is acting as the buyer to start the payment flow.
POST/partner/transactions/:uuid/buyer/pay
5Buyer: confirm payment
POST /api/partner/transactions/:uuid/buyer/confirm — after buyer approval (for sandbox, this happens immediately). Advances transaction.Stage to 'funded'.
POST/partner/transactions/:uuid/buyer/confirm
6Seller: mark shipped
POST /api/partner/transactions/:uuid/seller/mark-shipped — advances stage to 'delivery' and fires checkout_session.shipped. deliveryNotes tell the buyer how to access what was delivered; they are encrypted and never sent in webhooks.
POST/partner/transactions/:uuid/seller/mark-shipped
7Buyer: mark received (start inspection)
POST /api/partner/transactions/:uuid/buyer/mark-received — transitions to 'inspection' stage and starts the inspection window.
POST/partner/transactions/:uuid/buyer/mark-received
8Buyer: accept & release funds
POST /api/partner/transactions/:uuid/buyer/accept-inspection — releases funds to seller via EscrowService and fires checkout_session.inspection_accepted.
POST/partner/transactions/:uuid/buyer/accept-inspection