{"openapi":"3.1.0","info":{"title":"SuyPay API","version":"2026-10-01","description":"Payment Orchestration Platform: one API for Mercado Pago, Asaas, Efí, Stripe, Pagar.me, Appmax, Woovi, Inter, EvoPay, Wyvi Pay, Pagmaster, ClownPay, InvictusPay, TriboPay and RivooPay. Keys are \"full\" or \"charges\" (create and read payments by id only, for sales bots and third-party code)."},"servers":[{"url":"/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"suy_test_... or suy_live_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string","description":"Portuguese, says what to do"},"code":{"type":"string","description":"Normalized reason, e.g. card_declined, missing_document, invalid_credentials"},"param":{"type":"string"}}}}},"Customer":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"document":{"type":"string","description":"CPF/CNPJ"},"phone":{"type":"string"},"address":{"type":"object"},"ip":{"type":"string","description":"Buyer IP; defaults to the IP that called the API"}}},"NextAction":{"type":"object","properties":{"type":{"enum":["pix_qr","boleto","redirect","none"]},"qr_code":{"type":"string"},"qr_code_base64":{"type":"string"},"qr_code_url":{"type":"string","description":"Public image of the open Pix QR code (Discord embeds, e-mail)"},"digitable_line":{"type":"string"},"url":{"type":"string"}}},"Payment":{"type":"object","properties":{"id":{"type":"string","example":"pay_3kXy..."},"object":{"const":"payment"},"mode":{"enum":["test","live"]},"method":{"enum":["pix","card","boleto"],"nullable":true},"status":{"enum":["requires_method","pending","processing","succeeded","failed","canceled","refunded","partially_refunded"]},"amount":{"type":"integer","description":"cents"},"amount_refunded":{"type":"integer"},"currency":{"const":"BRL"},"fee":{"type":"integer"},"net":{"type":"integer"},"provider":{"type":"string"},"provider_payment_id":{"type":"string"},"next_action":{"$ref":"#/components/schemas/NextAction"},"metadata":{"type":"object"},"failure_reason":{"type":"string"},"failure_code":{"type":"string"},"end_to_end_id":{"type":"string"},"subscription_id":{"type":"string"},"splits":{"type":"array","items":{"type":"object","properties":{"subaccount_id":{"type":"string"},"amount":{"type":"integer","description":"cents"}}},"description":"Parts sent to subaccounts; the main account keeps the rest and pays the fees"},"payment_url":{"type":"string","description":"Customer page at pay.<domain>/<id>. When method is omitted, the customer selects an available method there. Stripe collects card and eligible wallet details in its hosted Checkout."},"created_at":{"type":"string","format":"date-time"}}},"Subaccount":{"type":"object","properties":{"id":{"type":"string","example":"sub_7Qp..."},"object":{"const":"subaccount"},"mode":{"enum":["test","live"]},"status":{"enum":["pending","active","refused","blocked","inactive"]},"status_detail":{"type":"string"},"provider":{"type":"string"},"provider_account_id":{"type":"string"},"provider_subaccount_id":{"type":"string","description":"Pagar.me recipient id, Asaas account id, Woovi Pix key"},"type":{"enum":["individual","company"]},"name":{"type":"string"},"document":{"type":"string"},"email":{"type":"string"},"details":{"type":"object","description":"Masked bank account, login e-mail, wallet id"},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}},"Refund":{"type":"object","properties":{"id":{"type":"string","example":"re_9Lm..."},"object":{"const":"refund"},"payment_id":{"type":"string"},"amount":{"type":"integer","description":"cents"},"status":{"enum":["pending","succeeded","failed"]},"reason":{"type":"string"},"source":{"enum":["suypay","provider"],"description":"suypay: asked through SuyPay · provider: made in the account dashboard, picked up by webhook or sync"},"provider_refund_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreatePayment":{"type":"object","required":["amount","customer"],"properties":{"method":{"enum":["pix","card","boleto"],"description":"Omit to let the customer choose on payment_url."},"amount":{"type":"integer","minimum":1},"currency":{"const":"BRL"},"description":{"type":"string"},"customer":{"$ref":"#/components/schemas/Customer"},"card":{"type":"object","properties":{"token":{"type":"string"},"installments":{"type":"integer"},"brand":{"type":"string"}}},"expires_in_minutes":{"type":"integer"},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"maxProperties":50,"description":"Up to 50 keys (40 chars) with string values (500 chars); copied to the account when it keeps metadata"},"provider_account_id":{"type":"string"},"splits":{"type":"array","maxItems":20,"items":{"type":"object","required":["subaccount_id"],"properties":{"subaccount_id":{"type":"string"},"amount":{"type":"integer","description":"cents of the gross amount"},"percentage":{"type":"number","description":"of the gross amount, instead of amount"}}},"description":"Send part of the payment to subaccounts of one connected account. Not allowed for restricted keys."}}},"Subscription":{"type":"object","description":"Pix Automático","properties":{"id":{"type":"string","example":"sub_8Hq..."},"object":{"const":"subscription"},"status":{"enum":["pending","active","canceled","refused","expired"]},"amount":{"type":["integer","null"]},"first_amount":{"type":"integer"},"frequency":{"enum":["weekly","monthly","quarterly","semiannually","annually"]},"start_date":{"type":"string","format":"date"},"next_charge_date":{"type":"string","format":"date"},"provider":{"type":"string"},"approval":{"type":["object","null"],"properties":{"qr_code":{"type":"string"},"qr_code_base64":{"type":"string"},"url":{"type":"string"}}}}},"CreateSubscription":{"type":"object","required":["customer","frequency"],"properties":{"customer":{"$ref":"#/components/schemas/Customer"},"frequency":{"enum":["weekly","monthly","quarterly","semiannually","annually"]},"amount":{"type":"integer"},"first_amount":{"type":"integer"},"description":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"retry":{"type":"boolean"},"metadata":{"type":"object"},"provider_account_id":{"type":"string"}}},"Dispute":{"type":"object","properties":{"id":{"type":"string","example":"dp_2Kd..."},"object":{"const":"dispute"},"kind":{"enum":["med","chargeback"]},"status":{"enum":["open","under_review","won","lost","canceled"]},"amount":{"type":"integer"},"reason":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"payment_id":{"type":"string"},"provider":{"type":"string"}}},"Payout":{"type":"object","properties":{"id":{"type":"string","example":"po_7Rt..."},"object":{"const":"payout"},"status":{"enum":["pending","processing","paid","failed","canceled"]},"amount":{"type":"integer","description":"cents"},"fee":{"type":["integer","null"]},"provider":{"type":"string"},"provider_account_id":{"type":"string"},"destination":{"type":"object","description":"{ type: \"account\" } or { type: \"pix_key\", key_type, key (masked), label }"},"uncertain":{"type":"boolean","description":"The account did not confirm: do not create another payout, SuyPay keeps checking"},"failure_code":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"paid_at":{"type":["string","null"],"format":"date-time"}}},"Event":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"event"},"type":{"type":"string"},"created":{"type":"integer"},"data":{"type":"object","properties":{"object":{}}}}}}},"paths":{"/payments":{"post":{"summary":"Create a payment","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayment"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}}}},"get":{"summary":"List payments","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"method","in":"query","schema":{"type":"string"}},{"name":"provider","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"}}}}}}}}},"/payments/{id}":{"get":{"summary":"Retrieve a payment (with attempts, refunds and events)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}}}}},"/payments/{id}/refund":{"post":{"summary":"Refund (full or partial). Send Idempotency-Key to retry safely.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer"},"reason":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"refund":{"$ref":"#/components/schemas/Refund"},"payment":{"$ref":"#/components/schemas/Payment"}}}}}}}}},"/payments/{id}/cancel":{"post":{"summary":"Cancel a payment nobody paid yet (the Pix QR or boleto stops working)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}}}}},"/payments/{id}/sync":{"post":{"summary":"Re-fetch status from the provider","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}}}}},"/payments/{id}/simulate":{"post":{"summary":"Test mode: mark a payment as paid (SuyPay Sandbox, or the Asaas, Inter or RivooPay sandbox)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}}}}},"/payments/{id}/simulate-dispute":{"post":{"summary":"Test mode: open a MED/chargeback on a paid sandbox payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}}}}},"/subscriptions":{"get":{"summary":"List Pix Automático","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}}}},"post":{"summary":"Create a Pix Automático (returns the approval QR code)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscription"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}}}}},"/subscriptions/{id}":{"get":{"summary":"Retrieve a Pix Automático with its cycles","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}}}}},"/subscriptions/{id}/charge":{"post":{"summary":"Charge one cycle now (variable amount)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer"},"due_date":{"type":"string","format":"date"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}}}}},"/subscriptions/{id}/cancel":{"post":{"summary":"Cancel a Pix Automático","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}}}}},"/subscriptions/{id}/simulate":{"post":{"summary":"Test mode: approve a sandbox Pix Automático","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}}}}},"/disputes":{"get":{"summary":"List MED and chargebacks","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"payment_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dispute"}}}}}}}}}},"/disputes/{id}":{"get":{"summary":"Retrieve a dispute","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}}}}},"/disputes/{id}/evidence":{"post":{"summary":"Send your defense (Stripe, Woovi)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"urls":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}}}}},"/balances":{"get":{"summary":"Balance of each active account in the key mode, and which ones pay out by API","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/payouts":{"get":{"summary":"List payouts","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"provider_account_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}}}}}}}}},"post":{"summary":"Pay out to the account registered in the provider or to a saved Pix key. Requires Idempotency-Key and, by API, payouts turned on by the owner.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_account_id","amount","destination"],"properties":{"provider_account_id":{"type":"string"},"amount":{"type":"integer","minimum":1},"description":{"type":"string","maxLength":140},"metadata":{"type":"object"},"destination":{"oneOf":[{"type":"object","properties":{"type":{"const":"account"}}},{"type":"object","properties":{"type":{"const":"pix_key"},"destination_id":{"type":"string"}}}]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"403":{"description":"payouts_api_disabled or restricted_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Daily limit or provider refusal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}":{"get":{"summary":"Retrieve a payout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}}}}},"/payouts/{id}/sync":{"post":{"summary":"Ask the account for the payout state now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}}}}},"/payout-destinations":{"get":{"summary":"Saved Pix keys (masked). Created only by the owner in the dashboard.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/subaccounts":{"get":{"summary":"List subaccounts","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"provider_account_id","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subaccount"}}}}}}}}},"post":{"summary":"Create a subaccount (Pagar.me recipient, Asaas subconta, Woovi subconta). Required fields depend on the provider: see /providers capabilities.subaccounts.requires.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_account_id","name","document"],"properties":{"provider_account_id":{"type":"string"},"type":{"enum":["individual","company"]},"name":{"type":"string"},"document":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"birthdate":{"type":"string","format":"date"},"mother_name":{"type":"string"},"occupation":{"type":"string"},"monthly_income":{"type":"integer","description":"cents"},"address":{"type":"object"},"bank_account":{"type":"object"},"pix_key":{"type":"object"},"company":{"type":"object"},"partner":{"type":"object"},"transfer_interval":{"enum":["daily","weekly","monthly"]},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}},"400":{"description":"A field the provider requires is missing (error.param)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subaccounts/{id}":{"get":{"summary":"Retrieve a subaccount with totals and its recent split payments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}}}},"patch":{"summary":"Change name or metadata in SuyPay","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}}}}},"/subaccounts/{id}/sync":{"post":{"summary":"Ask the provider for the subaccount status now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subaccount"}}}}}}},"/subaccounts/{id}/onboarding-link":{"post":{"summary":"Link where the owner proves identity and sends documents (Pagar.me KYC, Asaas)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expires_at":{"type":"string"}}}}}}}}},"/subaccounts/{id}/balance":{"get":{"summary":"Balance of the subaccount","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/subaccounts/{id}/withdrawals":{"get":{"summary":"Withdrawals of this subaccount","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}}}}}}}}},"post":{"summary":"Withdraw to the subaccount own registered destination. Requires Idempotency-Key and, by API, payouts turned on.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"cents; ignored where the provider withdraws the whole balance (Woovi)"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}}}}},"/routing/simulate":{"post":{"summary":"Dry-run routing for a method/amount","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["method","amount"],"properties":{"method":{"type":"string"},"amount":{"type":"integer"},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/providers":{"get":{"summary":"Supported providers and their credential fields","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/provider-accounts":{"get":{"summary":"Connected gateway accounts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Connect a gateway account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/routing-rules":{"get":{"summary":"List routing rules","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Create a routing rule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/events":{"get":{"summary":"Unified event log","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}}}},"/webhook-endpoints":{"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Create a webhook endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/analytics/overview":{"get":{"summary":"Volume, fees and approval rate by provider","parameters":[{"name":"days","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reconciliation-runs":{"get":{"summary":"List reconciliation runs","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Run reconciliation for a period","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}