openapi: 3.0.3
info:
title: Efí Pay Cobranças API
description: >-
Billing API for Efí Pay (formerly Gerencianet). Issue boletos (Brazilian bank
slips), Bolix (next-business-day boletos), carnês (installment booklets),
payment links, credit card charges, subscriptions/recurring billing, and
marketplace payment splits. OAuth2 with HTTP Basic for client_credentials.
version: "1.0"
contact:
name: Efí Pay Developer Support
url: https://dev.efipay.com.br
license:
name: Proprietary
servers:
- url: https://cobrancas.api.efipay.com.br/v1
description: Production
- url: https://cobrancas-h.api.efipay.com.br/v1
description: Homologation (Sandbox)
security:
- oauth2ClientCredentials: []
tags:
- name: Authorization
- name: Charges
- name: Carnets
- name: Subscriptions
- name: Plans
- name: Payment Links
- name: Notifications
- name: Card Payments
paths:
/authorize:
post:
tags: [Authorization]
summary: Issue Access Token
description: Exchange client_id and client_secret (HTTP Basic) for an OAuth2 access token used to authenticate subsequent Cobranças API calls.
operationId: authorize
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
grant_type:
type: string
enum: [client_credentials]
responses:
"200":
description: Access token issued
/charge:
post:
tags: [Charges]
summary: Create Charge
operationId: createCharge
responses: { "200": { description: Charge created } }
/charge/one-step:
post:
tags: [Charges]
summary: Create One Step Charge
operationId: createOneStepCharge
responses: { "200": { description: Charge created } }
/charge/one-step/link:
post:
tags: [Payment Links]
summary: Create One Step Charge Link
operationId: createOneStepLink
responses: { "200": { description: Link created } }
/charge/{id}:
get:
tags: [Charges]
summary: Detail Charge
operationId: detailCharge
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Charge detail } }
/charges:
get:
tags: [Charges]
summary: List Charges
operationId: listCharges
responses: { "200": { description: Charges list } }
/charge/{id}/cancel:
put:
tags: [Charges]
summary: Cancel Charge
operationId: cancelCharge
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Cancelled } }
/charge/{id}/pay:
post:
tags: [Charges]
summary: Define Payment Method
operationId: definePayMethod
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Method applied } }
/charge/{id}/billet:
put:
tags: [Charges]
summary: Update Billet
operationId: updateBillet
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Updated } }
/charge/{id}/billet/resend:
post:
tags: [Charges]
summary: Send Billet Email
operationId: sendBilletEmail
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Email queued } }
/charge/{id}/metadata:
put:
tags: [Charges]
summary: Update Charge Metadata
operationId: updateChargeMetadata
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Metadata updated } }
/charge/{id}/history:
post:
tags: [Charges]
summary: Create Charge History Note
operationId: createChargeHistory
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Note added } }
/charge/{id}/balance-sheet:
post:
tags: [Charges]
summary: Define Balance Sheet Billet
operationId: defineBalanceSheetBillet
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Balance sheet set } }
/charge/{id}/settle:
put:
tags: [Charges]
summary: Settle Charge Manually
operationId: settleCharge
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Settled } }
/charge/{id}/retry:
post:
tags: [Card Payments]
summary: Retry Card Payment
operationId: cardPaymentRetry
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Retried } }
/charge/card/{id}/refund:
post:
tags: [Card Payments]
summary: Refund Card Charge
operationId: refundCard
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Refund issued } }
/charge/{id}/link:
post:
tags: [Payment Links]
summary: Create Charge Link
operationId: linkCharge
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Link created } }
put:
tags: [Payment Links]
summary: Update Charge Link
operationId: updateChargeLink
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Link updated } }
/charge/{id}/link/resend:
post:
tags: [Payment Links]
summary: Send Link Email
operationId: sendLinkEmail
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Email queued } }
/carnet:
post:
tags: [Carnets]
summary: Create Carnet
operationId: createCarnet
responses: { "200": { description: Carnet created } }
/carnet/{id}:
get:
tags: [Carnets]
summary: Detail Carnet
operationId: detailCarnet
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Carnet detail } }
/carnet/{id}/parcels:
put:
tags: [Carnets]
summary: Update Carnet Parcels
operationId: updateCarnetParcels
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Parcels updated } }
/carnet/{id}/parcel/{parcel}:
put:
tags: [Carnets]
summary: Update Carnet Parcel
operationId: updateCarnetParcel
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
- { name: parcel, in: path, required: true, schema: { type: integer } }
responses: { "200": { description: Parcel updated } }
/carnet/{id}/parcel/{parcel}/cancel:
put:
tags: [Carnets]
summary: Cancel Carnet Parcel
operationId: cancelCarnetParcel
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
- { name: parcel, in: path, required: true, schema: { type: integer } }
responses: { "200": { description: Cancelled } }
/carnet/{id}/parcel/{parcel}/settle:
put:
tags: [Carnets]
summary: Settle Carnet Parcel
operationId: settleCarnetParcel
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
- { name: parcel, in: path, required: true, schema: { type: integer } }
responses: { "200": { description: Settled } }
/carnet/{id}/parcel/{parcel}/resend:
post:
tags: [Carnets]
summary: Send Carnet Parcel Email
operationId: sendCarnetParcelEmail
parameters:
- { name: id, in: path, required: true, schema: { type: integer } }
- { name: parcel, in: path, required: true, schema: { type: integer } }
responses: { "200": { description: Email queued } }
/carnet/{id}/cancel:
put:
tags: [Carnets]
summary: Cancel Carnet
operationId: cancelCarnet
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Cancelled } }
/carnet/{id}/settle:
put:
tags: [Carnets]
summary: Settle Carnet
operationId: settleCarnet
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Settled } }
/carnet/{id}/history:
post:
tags: [Carnets]
summary: Create Carnet History Note
operationId: createCarnetHistory
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Note added } }
/carnet/{id}/metadata:
put:
tags: [Carnets]
summary: Update Carnet Metadata
operationId: updateCarnetMetadata
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Metadata updated } }
/carnet/{id}/resend:
post:
tags: [Carnets]
summary: Send Carnet Email
operationId: sendCarnetEmail
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Email queued } }
/plans:
get:
tags: [Plans]
summary: List Plans
operationId: listPlans
responses: { "200": { description: Plans } }
/plan:
post:
tags: [Plans]
summary: Create Plan
operationId: createPlan
responses: { "200": { description: Plan created } }
/plan/{id}:
put:
tags: [Plans]
summary: Update Plan
operationId: updatePlan
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Updated } }
delete:
tags: [Plans]
summary: Delete Plan
operationId: deletePlan
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Deleted } }
/plan/{id}/subscription:
post:
tags: [Subscriptions]
summary: Create Subscription
operationId: createSubscription
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Subscription created } }
/plan/{id}/subscription/one-step:
post:
tags: [Subscriptions]
summary: Create One Step Subscription
operationId: createOneStepSubscription
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Subscription created } }
/plan/{id}/subscription/one-step/link:
post:
tags: [Subscriptions]
summary: Create One Step Subscription Link
operationId: createOneStepSubscriptionLink
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Link created } }
/subscription/{id}:
get:
tags: [Subscriptions]
summary: Detail Subscription
operationId: detailSubscription
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Subscription detail } }
put:
tags: [Subscriptions]
summary: Update Subscription
operationId: updateSubscription
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Updated } }
/subscription/{id}/pay:
post:
tags: [Subscriptions]
summary: Define Subscription Payment Method
operationId: defineSubscriptionPayMethod
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Applied } }
/subscription/{id}/cancel:
put:
tags: [Subscriptions]
summary: Cancel Subscription
operationId: cancelSubscription
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Cancelled } }
/subscription/{id}/metadata:
put:
tags: [Subscriptions]
summary: Update Subscription Metadata
operationId: updateSubscriptionMetadata
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Updated } }
/subscription/{id}/history:
post:
tags: [Subscriptions]
summary: Create Subscription History Note
operationId: createSubscriptionHistory
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Note added } }
/charge/{id}/subscription/resend:
post:
tags: [Subscriptions]
summary: Send Subscription Link Email
operationId: sendSubscriptionLinkEmail
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
responses: { "200": { description: Email queued } }
/installments:
get:
tags: [Card Payments]
summary: Get Installments
operationId: getInstallments
responses: { "200": { description: Installments } }
/notification/{token}:
get:
tags: [Notifications]
summary: Get Notification
operationId: getNotification
parameters: [{ name: token, in: path, required: true, schema: { type: string } }]
responses: { "200": { description: Notification payload } }
components:
securitySchemes:
oauth2ClientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://cobrancas.api.efipay.com.br/v1/authorize
scopes: {}
schemas:
Charge:
type: object
properties:
charge_id: { type: integer }
status: { type: string, enum: [new, waiting, paid, unpaid, refunded, contested, settled, link, identified, canceled, expired] }
total: { type: integer, description: Total in cents }
items:
type: array
items:
type: object
properties:
name: { type: string }
value: { type: integer }
amount: { type: integer }
payment:
type: object
created_at: { type: string, format: date-time }
Subscription:
type: object
properties:
subscription_id: { type: integer }
plan_id: { type: integer }
status: { type: string }
next_execution: { type: string, format: date }
Plan:
type: object
properties:
plan_id: { type: integer }
name: { type: string }
interval: { type: integer }
repeats: { type: integer, nullable: true }