{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-payments/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Scheduled payments","description":"Start today using our public API to power your next project."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"scheduled-payments"},"children":["Scheduled payments"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Future-dated payments, priced on the day they execute."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledDate"]}," to a future date and the payment enters ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]}," — accepted and queued, with the FX rate locked ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["on the execution date"]},", not at creation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-shape"},"children":["The shape"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," and send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," (the destination amount) instead — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledDate"]}," are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mutually exclusive"]},", and violating that returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 invalid_schedule"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://public-sandbox.tryjeeves.com/v1/payments' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\" \\\n  -H \"Idempotency-Key: 6b1e2f47-9c30-4a85-b7d2-3e8f0a5c1d94\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"scheduledDate\": \"<a future date, YYYY-MM-DD>\",\n    \"amount\": \"43035.00\",\n    \"productAccountId\": \"2b6f0c94-7a15-4e83-9d20-6c8e3b5a1f79\",\n    \"beneficiaryId\": \"3f1c9a52-6b7e-4d80-9a13-5c2e8f0b4d76\",\n    \"beneficiaryPaymentMethodId\": \"b7d2e4a1-8c05-49f3-a6b2-1e7d9c3f5024\",\n    \"purposeCode\": \"purchase_of_services\",\n    \"reference\": \"Invoice 2026-0912\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledDate"]}," with a date in the future, written ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]}," is required on every payment, scheduled or not — leaving it out returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-different-from-an-immediate-payment"},"children":["What's different from an immediate payment"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Aspect"},"children":["Aspect"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Immediate"},"children":["Immediate"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Scheduled"},"children":["Scheduled"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Rate"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Locked by your quote before you pay"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Locked on the execution date — you don't know the source amount until then"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," (+ optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onQuoteExpiry"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledDate"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},"; no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["First status"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accepted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onQuoteExpiry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Applies"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Does not apply"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Everything else is identical: the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," is required and behaves the same, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purposeCode"]}," is mandatory with the same corridor rules, and validation runs before acceptance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tracking-a-scheduled-payment"},"children":["Tracking a scheduled payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payment sits in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]}," until the execution date, then moves through the normal lifecycle (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in-progress"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", or a failure state). Each transition arrives as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment.status.updated"]}," webhook; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/payments/{paymentId}"]}," shows ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledDate"]}," and the current status at any time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the rate locks at execution, review the payment's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceAmount"]}," once it leaves ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]}," — that's when you learn what the payment actually cost."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancelling-a-payment"},"children":["Cancelling a payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/payments/{paymentId}/cancel"]}," — scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payments:write"]},". There is no request body."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://public-sandbox.tryjeeves.com/v1/payments/7a3e5f21-9d64-4c18-b0a7-1f52e8c3d9b6/cancel' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentId\": \"7a3e5f21-9d64-4c18-b0a7-1f52e8c3d9b6\",\n  \"status\": \"canceled\",\n  \"canceledAt\": \"2026-11-02T16:20:45Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When you can cancel."]}," Only while the status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in-review"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]}," — including a payment held by an approval policy. An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accepted"]}," payment is released too quickly to cancel, and a payment that is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in-progress"]}," or later cannot be cancelled."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"code"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_not_found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unknown ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentId"]},", an id that isn't a UUID, a payment that belongs to another customer, or a payment that wasn't created through the API."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_cancelable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The payment isn't in a status that can be cancelled. This includes a payment that was already cancelled."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This call is not idempotent."]}," A retry returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 not_cancelable"]}," because the first call succeeded. After a timeout, read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/payments/{paymentId}"]}," to see whether the payment is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}," before you retry."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What a cancel does:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment.status.updated"]}," webhook is sent."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryPaymentMethodId"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when you read the payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The quote stays spent — it can't fund another payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A pending approval workflow for the payment is removed."]}]}]},"headings":[{"value":"Scheduled payments","id":"scheduled-payments","depth":1},{"value":"The shape","id":"the-shape","depth":2},{"value":"What's different from an immediate payment","id":"whats-different-from-an-immediate-payment","depth":2},{"value":"Tracking a scheduled payment","id":"tracking-a-scheduled-payment","depth":2},{"value":"Cancelling a payment","id":"cancelling-a-payment","depth":2}],"frontmatter":{"seo":{"title":"Scheduled payments"}},"lastModified":"2026-11-04T03:42:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/payments/payment-flow/scheduled-payments","userData":{"isAuthenticated":false,"teams":["anonymous"]}}