{"openapi":"3.1.0","info":{"title":"Pagar.me (BYOK) API","version":"0.1.0","description":"Pagar.me (BYOK) lets an AI assistant read your own Pagar.me data through the Pagar.me API with a key you supply (secret key (sk_...)). Read-only: 9 tools (list_orders, get_order, list_charges, list_customers, list_subscriptions, list_plans, list_invoices, list_payables, list_recipients). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached;...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-pagarme.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-pagarme/docs"},"termsOfService":"https://connectorbay.com/byok-pagarme/terms"},"servers":[{"url":"https://byok-pagarme.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-pagarme/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_orders":{"post":{"operationId":"list_orders","summary":"List orders newest first with code, amount in cents, status and customer; filter by status, customer, reference code or ","description":"List orders newest first with code, amount in cents, status and customer; filter by status, customer, reference code or creation dates. Use for \"Which Pagar.me orders were paid this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"enum":["pending","paid","canceled","failed"],"type":"string"},{"type":"null"}],"default":null,"description":"Order status: pending, paid, canceled or failed.","title":"Status"},"code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own reference code of the order.","title":"Code"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this customer id (cus_...).","title":"Customer Id"},"created_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or after this date, YYYY-MM-DD.","title":"Created Since"},"created_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or before this date, YYYY-MM-DD.","title":"Created Until"}},"title":"list_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one order by id with its items: status and amounts in cents (use list_charges with order_id for its charges). Use fo","description":"Get one order by id with its items: status and amounts in cents (use list_charges with order_id for its charges). Use for \"Show Pagar.me order or_ABC123 with its items\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Order id (or_...).","maxLength":200,"title":"Order Id","type":"string"}},"required":["order_id"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_charges":{"post":{"operationId":"list_charges","summary":"List charges newest first with amount and paid amount in cents, status, payment method, customer and last transaction st","description":"List charges newest first with amount and paid amount in cents, status, payment method, customer and last transaction status; card details are left out. Use for \"Which Pagar.me charges failed today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"enum":["pending","paid","canceled","processing","failed","overpaid","underpaid"],"type":"string"},{"type":"null"}],"default":null,"description":"Charge status: pending, paid, canceled, processing, failed, overpaid or underpaid.","title":"Status"},"payment_method":{"anyOf":[{"enum":["credit_card","boleto","bank_transfer","safetypay","voucher"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment method: credit_card, boleto, bank_transfer, safetypay or voucher.","title":"Payment Method"},"code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own reference code of the charge.","title":"Code"},"order_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only charges of this order id (or_...).","title":"Order Id"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this customer id (cus_...).","title":"Customer Id"},"created_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or after this date, YYYY-MM-DD.","title":"Created Since"},"created_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or before this date, YYYY-MM-DD.","title":"Created Until"}},"title":"list_chargesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_customers":{"post":{"operationId":"list_customers","summary":"List customers (id, name, email, delinquent flag, creation dates); documents, addresses and phones are left out. Use for","description":"List customers (id, name, email, delinquent flag, creation dates); documents, addresses and phones are left out. Use for \"Who are my Pagar.me customers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Customer name to filter by.","title":"Name"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Customer email to filter by.","title":"Email"},"code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own customer code.","title":"Code"}},"title":"list_customersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List subscriptions with status, interval, billing type, next billing time and customer; card details are left out. Use f","description":"List subscriptions with status, interval, billing type, next billing time and customer; card details are left out. Use for \"Which Pagar.me subscriptions are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"enum":["active","canceled","future"],"type":"string"},{"type":"null"}],"default":null,"description":"Subscription status: active, canceled or future.","title":"Status"},"billing_type":{"anyOf":[{"enum":["prepaid","postpaid","exact_day"],"type":"string"},{"type":"null"}],"default":null,"description":"Billing type: prepaid, postpaid or exact_day.","title":"Billing Type"},"plan_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions of this plan id (plan_...).","title":"Plan Id"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this customer id (cus_...).","title":"Customer Id"},"next_billing_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions whose next billing is on or after this date, YYYY-MM-DD.","title":"Next Billing Since"},"next_billing_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only subscriptions whose next billing is on or before this date, YYYY-MM-DD.","title":"Next Billing Until"},"created_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or after this date, YYYY-MM-DD.","title":"Created Since"},"created_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or before this date, YYYY-MM-DD.","title":"Created Until"}},"title":"list_subscriptionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_plans":{"post":{"operationId":"list_plans","summary":"List subscription plans with price scheme, interval, billing type and status. Use for \"Which Pagar.me plans are active\".","description":"List subscription plans with price scheme, interval, billing type and status. Use for \"Which Pagar.me plans are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Plan name to filter by.","title":"Name"},"status":{"anyOf":[{"enum":["active","inactive","deleted"],"type":"string"},{"type":"null"}],"default":null,"description":"Plan status: active, inactive or deleted.","title":"Status"},"created_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or after this date, YYYY-MM-DD.","title":"Created Since"},"created_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or before this date, YYYY-MM-DD.","title":"Created Until"}},"title":"list_plansArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_invoices":{"post":{"operationId":"list_invoices","summary":"List subscription invoices with amount in cents, status, payment method, due date, customer and subscription. Use for \"W","description":"List subscription invoices with amount in cents, status, payment method, due date, customer and subscription. Use for \"Which Pagar.me invoices are pending\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"status":{"anyOf":[{"enum":["pending","paid","canceled","scheduled","failed"],"type":"string"},{"type":"null"}],"default":null,"description":"Invoice status: pending, paid, canceled, scheduled or failed.","title":"Status"},"customer_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this customer id (cus_...).","title":"Customer Id"},"subscription_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices of this subscription id (sub_...).","title":"Subscription Id"},"due_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on or after this date, YYYY-MM-DD.","title":"Due Since"},"due_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices due on or before this date, YYYY-MM-DD.","title":"Due Until"},"created_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or after this date, YYYY-MM-DD.","title":"Created Since"},"created_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only items created on or before this date, YYYY-MM-DD.","title":"Created Until"}},"title":"list_invoicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_payables":{"post":{"operationId":"list_payables","summary":"List payables (receivables) with amount, fee, anticipation fee in cents, installment, payment date, type and status; fil","description":"List payables (receivables) with amount, fee, anticipation fee in cents, installment, payment date, type and status; filter by status, type, recipient or charge. Use for \"How much will Pagar.me pay me next month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many items to return (1 to 100).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"forward_cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page, taken from the previous answer's paging.","title":"Forward Cursor"},"status":{"anyOf":[{"enum":["paid","waiting_funds"],"type":"string"},{"type":"null"}],"default":null,"description":"Payable status: paid or waiting_funds.","title":"Status"},"type":{"anyOf":[{"enum":["chargeback","refund","chargeback_refund","credit"],"type":"string"},{"type":"null"}],"default":null,"description":"Payable type: chargeback, refund, chargeback_refund or credit.","title":"Type"},"recipient_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payables of this recipient id (re_...).","title":"Recipient Id"},"charge_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payables of this charge id (ch_...).","title":"Charge Id"},"created_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payables created on or after this date, YYYY-MM-DD (default: the last 6 months).","title":"Created Since"},"created_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payables created on or before this date, YYYY-MM-DD.","title":"Created Until"},"payment_date_since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payables paid on or after this date, YYYY-MM-DD.","title":"Payment Date Since"},"payment_date_until":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payables paid on or before this date, YYYY-MM-DD.","title":"Payment Date Until"}},"title":"list_payablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_recipients":{"post":{"operationId":"list_recipients","summary":"List recipients (split-payment receivers) with name, email, type, status and transfer settings; documents and bank accou","description":"List recipients (split-payment receivers) with name, email, type, status and transfer settings; documents and bank accounts are left out. Use for \"Which recipients do I have on Pagar.me\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items per page (1 to 30).","title":"Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_recipientsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}