{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-payments/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Beneficiaries","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":"beneficiaries"},"children":["Beneficiaries"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The people and businesses you pay, with their attached payment methods."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment needs two IDs from this endpoint: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryId"]}," (who) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryPaymentMethodId"]}," (how — which of their attached payment methods receives the funds)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listing-beneficiaries"},"children":["Listing beneficiaries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/beneficiaries"]}," — scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:read"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl 'https://public-sandbox.tryjeeves.com/v1/beneficiaries?page=1&limit=50' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    {\n      \"beneficiaryId\": \"3f1c9a52-6b7e-4d80-9a13-5c2e8f0b4d76\",\n      \"entityType\": \"individual\",\n      \"firstName\": \"Ana\",\n      \"lastName\": \"Gómez\",\n      \"name\": null,\n      \"bankCountry\": \"MX\",\n      \"bankCurrency\": \"MXN\",\n      \"createdAt\": \"2026-09-10T14:02:11Z\",\n      \"paymentMethods\": [\n        {\n          \"paymentMethodId\": \"b7d2e4a1-8c05-49f3-a6b2-1e7d9c3f5024\",\n          \"paymentMethod\": \"spei\",\n          \"accountNumber\": \"••••0001\"\n        }\n      ]\n    },\n    {\n      \"beneficiaryId\": \"8a4e7c13-2d95-4f6b-8e01-7b3a5d9c2f48\",\n      \"entityType\": \"business\",\n      \"firstName\": null,\n      \"lastName\": null,\n      \"name\": \"Tortillería del Norte S.A. de C.V.\",\n      \"bankCountry\": \"MX\",\n      \"bankCurrency\": \"MXN\",\n      \"createdAt\": \"2026-09-11T09:41:55Z\",\n      \"paymentMethods\": [\n        { \"paymentMethodId\": \"c91a06b4-7f38-4e52-b8d7-0a5c4e1f9362\", \"paymentMethod\": \"spei\", \"accountNumber\": \"••••4417\" },\n        { \"paymentMethodId\": \"d04b18e7-5a29-4c63-9f81-2d6e7b0a4c15\", \"paymentMethod\": \"wire\", \"accountNumber\": \"••••1897\" }\n      ]\n    }\n  ],\n  \"count\": 42\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reading-the-shape"},"children":["Reading the shape"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entityType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]}," populates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]}," populates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCountry"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCurrency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Where and in what currency this beneficiary is paid — this is the destination side of your corridor."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Every live method attached to the beneficiary (",{"$$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"]},", …). May be empty — a beneficiary with no methods can't be paid yet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accountNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Masked — only the last four characters are shown. An account of four characters or fewer is masked completely, and a method with no account number is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field"]}," on a beneficiary or on a payment method: deleted beneficiaries and deleted payment methods are simply never returned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pick the method whose rail you want: for the business above, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spei"]}," delivers via the local Mexican rail, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire"]}," via international wire."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Destination coverage:"]}," beneficiaries can be paid in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["190+ countries"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCountry"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCurrency"]}," and the attached payment methods define the corridor — the local rail differs by country (SPEI in Mexico, PIX in Brazil, SEPA in the Eurozone, ACH in the US, Faster Payments in the UK, and so on), with international wire as the broad fallback. The examples in these docs use a handful of corridors for concreteness — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/coverage"},"children":["Destination coverage"]}," for the flagship rails and how to confirm a specific corridor."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination"},"children":["Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Page-based, matching the rest of the Jeeves Public API: pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," (1-based, default 1) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," (default 50, values above 200 are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["clamped to 200"]},", not rejected). A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}," parameter is also accepted — free text, up to 100 characters, matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}," as a substring and a payment method's account number by suffix. Any other query parameter is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 validation_failed"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code: unknown_field"]}," — unknown parameters are not ignored."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The envelope is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["count"]},", and nothing else. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["count"]}," is the total matching your query across all pages — stop once ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page × limit"]}," reaches it. The request ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," echoed back, so keep track of them yourself."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-one-beneficiary"},"children":["Getting one beneficiary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/beneficiaries/{beneficiaryId}"]}," — scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:read"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl 'https://public-sandbox.tryjeeves.com/v1/beneficiaries/3f1c9a52-6b7e-4d80-9a13-5c2e8f0b4d76' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["bare beneficiary object"]},", identical to one entry of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data[]"]}," in the list — there is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["count"]}," envelope. It includes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactInformation"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethods[]"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"beneficiaryId\": \"3f1c9a52-6b7e-4d80-9a13-5c2e8f0b4d76\",\n  \"entityType\": \"individual\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Gómez\",\n  \"name\": null,\n  \"bankCountry\": \"MX\",\n  \"bankCurrency\": \"MXN\",\n  \"contactInformation\": {\n    \"streetAddress\": null,\n    \"city\": null,\n    \"state\": null,\n    \"postcode\": null,\n    \"countryCode\": null,\n    \"phoneNumber\": null,\n    \"emailAddress\": null\n  },\n  \"createdAt\": \"2026-09-10T14:02:11Z\",\n  \"paymentMethods\": [\n    {\n      \"paymentMethodId\": \"b7d2e4a1-8c05-49f3-a6b2-1e7d9c3f5024\",\n      \"paymentMethod\": \"spei\",\n      \"accountNumber\": \"••••0001\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Account numbers are masked to the last four characters (an account of four characters or fewer is masked completely, and a method with no account number is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An unknown, deleted, malformed or other-customer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryId"]}," returns the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 beneficiary_not_found"]}," body — never a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", so the API never confirms that someone else's beneficiary exists."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-beneficiaries"},"children":["Creating beneficiaries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating a payee takes three calls: create the beneficiary, ask what the corridor needs, then attach a payment method. All three use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:write"]}," scope, except the schema read, which needs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:read"]},". Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:write"]}," to the scopes you request on ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/payment-flow/send-payment#1-get-an-access-token"},"children":["the token call"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1.-create-the-beneficiary"},"children":["1. Create the beneficiary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/beneficiaries"]}," — scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:write"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://public-sandbox.tryjeeves.com/v1/beneficiaries' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"entityType\": \"individual\",\n    \"firstName\": \"Ana\",\n    \"lastName\": \"Gómez\",\n    \"bankCountry\": \"MX\",\n    \"bankCurrency\": \"MXN\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"beneficiaryId\": \"3f1c9a52-6b7e-4d80-9a13-5c2e8f0b4d76\",\n  \"status\": \"active\",\n  \"createdAt\": \"2026-11-02T14:02:11Z\"\n}\n","lang":"json"},"children":[]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Rule"},"children":["Rule"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entityType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["For an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["For a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCountry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Uppercase ISO 3166-1 alpha-2, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCurrency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["One of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MXN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BRL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EUR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GBP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USDB"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USDC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USDT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EURC"]},". Any other value is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported_value"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each name field is at most 255 characters. A required name field that is missing, or one that belongs to the other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entityType"]},", is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},". Unknown fields are rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown_field"]},", and a JSON array body is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},". The beneficiary is created ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["with no payment methods"]}," — attach one in step 3."]},{"$$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":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation_failed"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request_body"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The body is not valid, or could not be parsed."]}]},{"$$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":["validation_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A name field is missing (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]},") or belongs to the other ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entityType"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown_field"]},"). The offending fields are listed in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorData.errors[]"]}]},", not in the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]},"."]}]},{"$$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":["validation_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCountry"]}," is well formed but not a known country: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported_value"]},"."]}]},{"$$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":["validation_failed"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[].code: duplicate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A beneficiary with the same name, bank country and bank currency already exists. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," names ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," for a business, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]}," for an individual. This also matches a Boleto-source vendor that the list endpoint doesn't show."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A name-field mismatch looks like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"message\": \"The name fields do not match entityType: individuals use firstName and lastName, businesses use name.\",\n  \"code\": \"validation_failed\",\n  \"statusCode\": 422,\n  \"requestId\": \"7186288b-2f41-4c6a-9d85-1b0e3a7c5f92\",\n  \"errorData\": {\n    \"errors\": [\n      { \"field\": \"firstName\", \"code\": \"required\", \"message\": \"firstName is required.\" },\n      { \"field\": \"lastName\", \"code\": \"required\", \"message\": \"lastName is required.\" },\n      { \"field\": \"name\", \"code\": \"unknown_field\", \"message\": \"name is not allowed.\" }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This call is not idempotent."]}," No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," is read; a header you send is ignored. The duplicate check is your retry protection. Two simultaneous identical requests can both succeed, because nothing enforces uniqueness at the database — don't fire the same create twice in parallel."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2.-ask-what-the-corridor-needs"},"children":["2. Ask what the corridor needs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/beneficiary-schemas"]}," — scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:read"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl 'https://public-sandbox.tryjeeves.com/v1/beneficiary-schemas?sourceCurrency=USD&productAccountType=self-funded&destinationCountry=MX&destinationCurrency=MXN&entityType=individual' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]},{"$$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":"Query parameter"},"children":["Query parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceCurrency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. The currency you pay from — one of the supported currencies listed for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCurrency"]}," above."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productAccountType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credit-line"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self-funded"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto-wallet"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destinationCountry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. Uppercase ISO 3166-1 alpha-2."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destinationCurrency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. The currency the beneficiary receives — one of the supported currencies listed for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCurrency"]}," above."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entityType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required, because the form depends on it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Optional. Narrows the response to one method, using a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," value as this endpoint returns it."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentMethods\": [\n    {\n      \"paymentMethod\": \"local_bank_transfer\",\n      \"fields\": [\n        {\n          \"fieldName\": \"accountNumber\",\n          \"type\": \"string\",\n          \"required\": true,\n          \"pattern\": \"^\\\\d{10,18}$\",\n          \"description\": \"Account number\"\n        },\n        {\n          \"fieldName\": \"bankCode\",\n          \"type\": \"string\",\n          \"required\": true,\n          \"description\": \"Bank code\"\n        }\n      ],\n      \"contactFields\": [],\n      \"purposeCodes\": [\n        { \"code\": \"purchase_of_services\", \"description\": \"Purchase of services\" },\n        { \"code\": \"travel\", \"description\": \"Travel\" }\n      ]\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The values above are illustrative — always read the real list for your corridor."]},{"$$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":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"What it is"},"children":["What it is"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The value to send, unchanged, as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," in step 3."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ fieldName, type, required, pattern?, allowedValues?, description }"]},", with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enum"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedValues"]}," entries can be strings or numbers. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fieldName"]}," values are the keys of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankingInformation"]}," in step 3."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactFields[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The same shape. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fieldName"]}," values are the keys of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactInformation"]},". Empty when the method needs none."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purposeCodes[]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ code, description }"]}," — the exact list that payment-time validation accepts."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Patterns and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purposeCode"]}," are enforced again when you create the payment. Your company must hold the funding source you name with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceCurrency"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productAccountType"]},"; the methods and purpose codes returned are those for that funding source."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Two vocabularies."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," here (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["local_bank_transfer"]},") is the value you send in step 3. When you later read the beneficiary, its methods are reported in a normalised vocabulary (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ach"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spei"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire"]},", and so on — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/coverage#all-payment-methods"},"children":["Coverage"]},"), so the two are not interchangeable."]}]},{"$$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":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A query parameter is missing or invalid. A missing one appears as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[].code: required"]}," — there is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missing_parameter"]}," code. A currency outside the supported list, or a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destinationCountry"]}," that is not an alpha-2 code, reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported_value"]},"."]}]},{"$$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":["unsupported_corridor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["No payment method is available for this destination."]}]},{"$$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":["unsupported_payment_method"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," you asked for isn't offered for this corridor."]}]},{"$$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":["validation_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," reports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported_value"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sourceCurrency"]}," when your company doesn't hold that funding source."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3.-attach-a-payment-method"},"children":["3. Attach a payment method"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/payment-methods"]}," — scope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaries:write"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://public-sandbox.tryjeeves.com/v1/payment-methods' \\\n  -H \"Authorization: Bearer $JEEVES_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"beneficiaryId\": \"3f1c9a52-6b7e-4d80-9a13-5c2e8f0b4d76\",\n    \"paymentMethod\": \"local_bank_transfer\",\n    \"bankingInformation\": { \"accountNumber\": \"0123456789\", \"bankCode\": \"021000021\" }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"paymentMethodId\": \"b7d2e4a1-8c05-49f3-a6b2-1e7d9c3f5024\",\n  \"status\": \"active\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethodId"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryPaymentMethodId"]}," when you ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/payments/payment-flow/send-payment#5-create-the-payment"},"children":["create a payment"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No corridor parameters."]}," The corridor is taken from the beneficiary's stored bank country and currency."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}]}," must be a value from the schema response in step 2, sent unchanged."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankingInformation"]}]}," keys must equal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields[].fieldName"]},", and each value is checked against its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pattern"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactInformation"]}]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phoneNumber"]}," takes the form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+<dialing code> <number>"]}," (for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+1 2125551234"]},") and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postcode"]}," is at most 15 characters; both are published as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pattern"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactFields"]},". It is required when the method's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactFields"]}," is not empty, unless the beneficiary already has that value stored. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactFields"]}," is empty, any contact key is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown_field"]},"."]}]},{"$$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":["beneficiary_not_found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unknown, deleted, malformed or other-customer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["beneficiaryId"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_method_already_exists"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The beneficiary already has a payment method on this rail."]}]},{"$$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":["validation_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors[]"]}," names ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankingInformation.<field>"]}," for banking fields, keeps ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contactInformation.<field>"]}," for contact fields and uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," for the method itself. Reasons: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_format"]}," (the value fails its pattern, which the message names), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unsupported_value"]}," (a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," the corridor doesn't offer), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown_field"]},". A wallet blocked by screening is also a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 validation_failed"]},", with no per-field detail."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One payment method per rail per beneficiary."]}," The duplicate check uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod"]}," only, not the account number. To replace a method you would have to delete the old one first, and the public API has no delete — plan the account number before you attach it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["This call is not idempotent."]}," No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," is read, and a retry after a success gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bank-detail validation is corridor-specific — a detail that fails the corridor's rules at payment time surfaces as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 validation_failed"]},"."]}]},"headings":[{"value":"Beneficiaries","id":"beneficiaries","depth":1},{"value":"Listing beneficiaries","id":"listing-beneficiaries","depth":2},{"value":"Reading the shape","id":"reading-the-shape","depth":2},{"value":"Pagination","id":"pagination","depth":2},{"value":"Getting one beneficiary","id":"getting-one-beneficiary","depth":2},{"value":"Creating beneficiaries","id":"creating-beneficiaries","depth":2},{"value":"1. Create the beneficiary","id":"1.-create-the-beneficiary","depth":3},{"value":"2. Ask what the corridor needs","id":"2.-ask-what-the-corridor-needs","depth":3},{"value":"3. Attach a payment method","id":"3.-attach-a-payment-method","depth":3}],"frontmatter":{"seo":{"title":"Beneficiaries"}},"lastModified":"2026-11-04T03:42:09.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/payments/funding/beneficiaries","userData":{"isAuthenticated":false,"teams":["anonymous"]}}