{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-payments/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Core concepts","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":"core-concepts"},"children":["Core concepts"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The entities of the Payment API and how they relate."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Five entities carry the whole model: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Company"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Funding accounts"]}," (product accounts), ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Beneficiaries"]}," (with their ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["payment methods"]},"), ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Quotes"]},", and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payments"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Company (you)\n ├── Funding accounts         what you pay FROM (productAccounts)\n │     self-funded · credit-line · crypto-wallet · jeeves-pay-*\n │\n ├── Beneficiaries           who you pay\n │     └── Payment methods   HOW each one is paid (spei, wire, ach, swift, …)\n │\n ├── Quotes                  a locked FX rate for one payment (single-use, expiring)\n │\n └── Payments                money in motion: quote + account + beneficiary\n       └── status history    pushed as payment.status.updated webhooks\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"company"},"children":["Company"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your company at Jeeves. Credentials belong to a company; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/product-accounts"]}," returns an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["array of companies"]},", one entry per company the credential covers — a single-company integration reads ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[0].productAccounts"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"funding-account-product-account"},"children":["Funding account (product account)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The account a payment is funded from — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productAccount"]}," in the API. You can hold several, across currencies and types (a USD fiat balance, a stablecoin wallet such as USDC, an MXN balance, credit in USD/MXN/BRL, …). Each has a type — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self-funded"]}," (your pre-funded balance), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credit-line"]}," (Jeeves credit; also what you send for a Bill Pay credit account, which ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/product-accounts"]}," reports as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jeeves-pay-credit"]},"), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto-wallet"]}," (stablecoin balance, currency reported as a ticker like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USDC"]},") — a currency, and a status. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]}," accounts can fund a payment"]},", and the account's currency must match the quote's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceCurrency"]},". Your FX rate and fees depend on the type, and the type shapes which purpose codes a corridor accepts."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"beneficiary"},"children":["Beneficiary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A person (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]},") or business (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]},") you pay. Individuals carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},"; businesses carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},". Each beneficiary has a bank country and currency, contact information, and zero or more attached ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["payment methods"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spei"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ach"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["swift"]},", …). You reference both on a payment: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryId"]}," plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryPaymentMethodId"]},". Deleted beneficiaries and methods are never returned by the API. You can read one beneficiary with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/beneficiaries/{beneficiaryId}"]}," and create one with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/beneficiaries"]}," — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/funding/beneficiaries#creating-beneficiaries"},"children":["Beneficiaries"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-method"},"children":["Payment method"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How one beneficiary is paid: a rail such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spei"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire"]},", with the account details that rail needs. A beneficiary holds ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["at most one payment method per rail"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/beneficiary-schemas"]}," tells you which methods a corridor offers and which ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankingInformation"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactInformation"]}," fields each needs, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/payment-methods"]}," attaches one. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]}," it returns is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryPaymentMethodId"]}," you send on a payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quote"},"children":["Quote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A locked FX rate for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one"]}," payment. Quotes are destination-amount based: you say what the beneficiary must receive, and the source amount is derived from the rate. A quote is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["single-use and expires"]}," — read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," from the response (the TTL is configured per company; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," means it doesn't expire). Reusing a consumed quote returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 quote_expired"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"corridor"},"children":["Corridor"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The combination of source currency and account type on one side and destination currency/country on the other. A corridor can be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["domestic"]}," — same currency and country on both sides (e.g. MXN → MXN to a Mexican business via SPEI) — and the flow is identical. The corridor decides which ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["purpose codes"]}," are valid and what beneficiary details are required. See the purpose-code table in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/payment-flow/send-payment#purpose-codes"},"children":["Send a payment"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"purpose-code"},"children":["Purpose code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A regulatory declaration of why the payment is being made — always a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["string identifier"]}," like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase_of_services"]},", never a number. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mandatory on every payment"]},", with no default. Each corridor accepts a fixed set of identifiers, listed in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purposeCodes[]"]}," by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/beneficiary-schemas"]}," (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/payment-flow/send-payment#purpose-codes"},"children":["Send a payment"]},"); omitting it is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", and an identifier outside the corridor's set is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 validation_failed"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency-key"},"children":["Idempotency key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A customer-generated UUID sent as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/payments"]},", unique per payment attempt and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["never expiring"]},". Same key + same body replays the original result byte for byte; same key + different body returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 idempotency_conflict"]},". On timeout or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]},", retry with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same"]}," key — a fresh key on retry is how duplicate payments happen."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requote"},"children":["Requote"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What happens when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onQuoteExpiry: requote"]}," rescues an expired quote: a new quote is priced at the current rate and used. The destination amount is unchanged; the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["source amount moves"]},". The response then carries both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quoteId"]}," (the quote that priced the payment) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originalQuoteId"]}," (the expired one you sent) — the one case where you pay a rate you were not previously shown."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"credential-vs.-scope"},"children":["Credential vs. scope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["credential"]}," is the client ID + secret pair and the client certificate issued by Jeeves — it identifies your company. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scopes"]}," are the permissions you request on each token (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payments:write"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quotes:write"]},", …); a token can never reach a capability outside its scopes. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:write"]}," covers creating beneficiaries and attaching payment methods, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payments:write"]}," covers creating and cancelling payments. Some scopes (the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*:multiple:*"]}," family, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cards:multiple:write"]},") are enabled on a credential only on request — ask Jeeves support."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancel"},"children":["Cancel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stopping a payment you no longer want to send. You can cancel only while the status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in-review"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]},"; the payment becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}," webhook is sent, and the quote stays spent. The call isn't idempotent. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/payments/{paymentId}/cancel"]}," — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/payment-flow/scheduled-payments#cancelling-a-payment"},"children":["Cancelling a payment"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"terminal-status"},"children":["Terminal status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A status a payment can never leave: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejected"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]},". Everything else (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accepted"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in-review"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in-progress"]},") is in flight. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failureReason"]}," is populated for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejected"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]},"."]}]},"headings":[{"value":"Core concepts","id":"core-concepts","depth":1},{"value":"Company","id":"company","depth":2},{"value":"Funding account (product account)","id":"funding-account-product-account","depth":2},{"value":"Beneficiary","id":"beneficiary","depth":2},{"value":"Payment method","id":"payment-method","depth":2},{"value":"Quote","id":"quote","depth":2},{"value":"Corridor","id":"corridor","depth":2},{"value":"Purpose code","id":"purpose-code","depth":2},{"value":"Idempotency key","id":"idempotency-key","depth":2},{"value":"Requote","id":"requote","depth":2},{"value":"Credential vs. scope","id":"credential-vs.-scope","depth":2},{"value":"Cancel","id":"cancel","depth":2},{"value":"Terminal status","id":"terminal-status","depth":2}],"frontmatter":{"seo":{"title":"Core concepts"}},"lastModified":"2026-11-04T03:42:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/payments/terminology","userData":{"isAuthenticated":false,"teams":["anonymous"]}}