{"openapi":"3.1.0","info":{"title":"joia API","version":"2026-11-04","description":"Collect Pix, Pix Automático and installment cards from Brazilian payers; settled and paid out automatically. All amounts are integer BRL cents."},"servers":[{"url":"https://sandbox.payjoia.com/v1","description":"Sandbox"}],"security":[{"bearer":[]}],"paths":{"/charges":{"post":{"operationId":"createCharge","summary":"Create a charge","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeCreate"}}}},"responses":{"200":{"description":"Existing charge for this order_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"order_id reused with another amount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listCharges","summary":"List charges","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Charge"}},"has_more":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/charges/{id}":{"get":{"operationId":"getCharge","summary":"Retrieve a charge by id or order_id","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"chg_… or your order_id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelCharge","summary":"Cancel a pending charge","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"chg_… or your order_id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/charges/{id}/refund":{"post":{"operationId":"refundCharge","summary":"Refund the payer (full or partial)","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"chg_… or order_id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."}}}}}},"responses":{"202":{"description":"Refund requested"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"Retrieve an event","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"evt_…"}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoint":{"get":{"operationId":"getWebhookEndpoint","summary":"Your webhook endpoint","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setWebhookEndpoint","summary":"Set your webhook endpoint URL","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoint/rotate_secret":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate the signing secret (returned once)","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pix-automatic/authorizations":{"post":{"operationId":"createPixAutomaticAuthorization","summary":"Create a Pix Automático authorization","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Authorization"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listPixAutomaticAuthorizations","summary":"List authorizations","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Authorization"}},"has_more":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pix-automatic/authorizations/{id}":{"get":{"operationId":"getPixAutomaticAuthorization","summary":"Retrieve an authorization (with its charges)","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"pxa_… or your reference"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Authorization"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelPixAutomaticAuthorization","summary":"Cancel an authorization","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"pxa_… or your reference"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Authorization"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pix-automatic/authorizations/{id}/charges":{"post":{"operationId":"createPixAutomaticCycle","summary":"Create a cycle (variable-amount authorizations)","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"pxa_… or reference"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_id","amount","due_date"],"properties":{"order_id":{"type":"string"},"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"due_date":{"type":"string","format":"date"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts":{"post":{"operationId":"createPayout","summary":"Pay out to a registered destination or a brCode","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":100}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused with different parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listPayouts","summary":"List payouts","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payout"}},"has_more":{"type":"boolean"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payouts/{id}":{"get":{"operationId":"getPayout","summary":"Retrieve a payout","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"po_…"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/destinations":{"get":{"operationId":"listDestinations","summary":"Registered payout destinations","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Balance","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/daily":{"get":{"operationId":"getDailyReport","summary":"Daily report (America/Sao_Paulo)","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"date","in":"query","schema":{"type":"string","format":"date"}},{"name":"format","in":"query","schema":{"enum":["json","csv"]}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"operationId":"listEvents","summary":"Events (same payloads as webhooks)","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"after","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/accounts":{"get":{"operationId":"listAccounts","summary":"Connected accounts (platforms)","responses":{"200":{"description":"OK"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox/charges/{id}/pay":{"post":{"operationId":"sandboxPayCharge","summary":"Sandbox: simulate the payer","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"chg_…"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["method"],"properties":{"method":{"enum":["pix","card"]},"installments":{"type":"integer","minimum":1,"maximum":21}}}}}},"responses":{"200":{"description":"Simulated"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox/pix-automatic/authorizations/{id}/next-cycle":{"post":{"operationId":"sandboxNextCycle","summary":"Sandbox: debit the next cycle","parameters":[{"name":"Joia-Account","in":"header","required":false,"schema":{"type":"string"},"description":"Platforms: act on a connected account (mer_…)."},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"pxa_… or reference"}],"responses":{"200":{"description":"Simulated"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Not possible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"joia_test_… (sandbox) or joia_live_… (live)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}}},"Payer":{"type":"object","required":["name","document"],"properties":{"name":{"type":"string"},"document":{"type":"string","description":"CPF (11) or CNPJ (14) digits"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"ChargeCreate":{"type":"object","required":["order_id","amount"],"properties":{"order_id":{"type":"string","maxLength":100},"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00).","minimum":500},"methods":{"type":"array","items":{"enum":["pix","card"]},"default":["pix","card"]},"max_installments":{"type":"integer","minimum":1,"maximum":21,"default":12},"fees_paid_by":{"enum":["merchant","payer"]},"payer":{"$ref":"#/components/schemas/Payer"},"description":{"type":"string","maxLength":200},"expires_in_minutes":{"type":"integer","minimum":15,"maximum":10080,"default":1440},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"Charge":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"charge"},"type":{"enum":["one_time","pix_automatic"]},"order_id":{"type":"string"},"status":{"enum":["pending","paid","expired","failed","refunded","partially_refunded","chargeback","cancelled"]},"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"amount_paid":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"currency":{"const":"BRL"},"methods":{"type":"array","items":{"type":"string"}},"max_installments":{"type":"integer"},"installments":{"type":["integer","null"]},"pay_url":{"type":"string"},"pix":{"type":["object","null"],"properties":{"copy_paste":{"type":"string"},"qr_code_png_base64":{"type":"string"},"expires_at":{"type":"string"}}},"card_checkout_url":{"type":["string","null"]},"authorization_id":{"type":["string","null"]},"settlement":{"type":"object","properties":{"provider_net":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"intermediation_fee":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"reserve_held":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"refunds_and_chargebacks":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"net_to_balance":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."}}},"metadata":{"type":"object"},"paid_at":{"type":["string","null"]},"created_at":{"type":"string"}}},"AuthorizationCreate":{"type":"object","required":["reference","payer","frequency","first_payment_amount","start_date"],"properties":{"reference":{"type":"string"},"payer":{"$ref":"#/components/schemas/Payer"},"frequency":{"enum":["weekly","monthly","quarterly","semiannually","annually"]},"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"first_payment_amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"description":{"type":"string","maxLength":35},"retry_on_failure":{"type":"boolean"},"metadata":{"type":"object"}}},"Authorization":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"pix_automatic_authorization"},"reference":{"type":"string"},"status":{"enum":["pending","active","cancelled","refused","expired"]},"frequency":{"type":"string"},"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"amount_type":{"enum":["fixed","variable"]},"first_payment":{"type":["object","null"]},"start_date":{"type":"string"},"charges":{"type":"array","items":{"$ref":"#/components/schemas/Charge"}}}},"PayoutCreate":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"destination_id":{"type":"string"},"brcode":{"type":"string"},"reference":{"type":"string","maxLength":140}}},"Payout":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"payout"},"status":{"enum":["processing","paid","failed","blocked"]},"method":{"enum":["pix_key","brcode"]},"amount":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"fee":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"destination":{"type":"object"},"reference":{"type":["string","null"]},"end_to_end_id":{"type":["string","null"]},"receipt_url":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string"}}},"Balance":{"type":"object","properties":{"object":{"const":"balance"},"currency":{"const":"BRL"},"available":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"reserved":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"total":{"type":"integer","description":"Amount in BRL cents (150000 = R$ 1,500.00)."},"payout_mode":{"enum":["per_payment","daily","manual"]}}}}}}