Skip to main content
API docs by Redocly

OpenPix (1.0.0)

Download OpenAPI specification:Download

A OpenPix é uma Plataforma de Gestão de Pagamentos. Para utilizar nossa API você deve acessar https://api.openpix.com.br/ e somente o mesmo. A OpenPix não aceita subdominios para a API.

Veja como configurar seu acesso a nossa API aqui.

account

Endpoint to manage Accounts

Get an Account

Authorizations:
AppID
path Parameters
accountId
required
string
Example: 6290ccfd42831958a405debc

ID of the Account

Responses

Response samples

Content type
application/json
{
  • "account": {
    }
}

Get a list of Accounts

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Withdraw from an Account

An additional fee may be charged depending on the minimum free withdrawal amount. See more about at https://developers.openpix.com.br/docs/FAQ/faq-virtual-account/#onde-posso-consultar-as-taxas-da-minha-conta-virtual

Authorizations:
AppID
path Parameters
accountId
required
string
Example: 6290ccfd42831958a405debc

ID of the Account

Request Body schema: application/json
required
value
number

Value in cents

Responses

Request samples

Content type
application/json
{
  • "value": 7000
}

Response samples

Content type
application/json
{
  • "withdraw": {
    }
}

cashback-fidelity

Endpoint to manage exclusive cashbacks

Get the exclusive cashback amount an user still has to receive by taxID.

Authorizations:
AppID
path Parameters
taxID
required
string
Examples:
  • 60151449000182 -

The raw tax ID from the customer you want to get the balance.

Responses

Response samples

Content type
application/json
{
  • "balance": 0,
  • "status": "string"
}

Get or create cashback for a customer.

Create a new cashback exclusive for the customer with a given taxID. If the customer already has a pending excluisve cashback, this endpoint will return it instead.

Authorizations:
AppID
Request Body schema: application/json
required

Customer's taxID and the cash

taxID
string

Customer taxID (CPF or CNPJ)

value
number

Cashback value in centavos

Responses

Request samples

Content type
application/json
{
  • "value": 100,
  • "taxID": 11111111111
}

Response samples

Content type
application/json
{
  • "cashback": {
    },
  • "message": "string"
}

charge

Endpoint to manage Charges

Get an image of Qr Code from a Charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

charge link payment ID

query Parameters
size
string
Examples:
  • size=768 -

Size for the image. This size should be between 600 and 4096. if the size parameter was not passed, the default value will be 1024.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Delete a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

charge ID or correlation ID. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "id": "fe7834b4060c488a9b0f89811be5f5cf"
}

Get one charge

Authorizations:
AppID
path Parameters
id
required
string
Example: fe7834b4060c488a9b0f89811be5f5cf

charge ID or correlation ID. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Responses

Response samples

Content type
application/json
{
  • "charge": {
    }
}

Get a list of charges

Authorizations:
AppID
query Parameters
start
string <date-time> (Start Date)
Example: start=2020-01-01T00:00:00Z

Start date used in the query. Complies with RFC 3339.

end
string <date-time> (End Date)
Example: end=2020-12-01T17:00:00Z

End date used in the query. Complies with RFC 3339.

status
string
Enum: "ACTIVE" "COMPLETED" "EXPIRED"
customer
string

Customer Correlation ID

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "charges": {
    }
}

Create a new Charge

Endpoint to create a new Charge for a customer

Authorizations:
AppID
query Parameters
return_existing
boolean
Examples:
  • return_existing=true -

Make the endpoint idempotent, will return an existent charge if already has a one with the correlationID

Request Body schema: application/json
required

Data to create a new charge

correlationID
required
string

Your correlation ID to keep track of this charge

value
required
number

Value in cents of this charge

type
string
Enum: "DYNAMIC" "OVERDUE"

Charge type is used to determine whether a charge will have a deadline, fines and interests

comment
string

Comment to be added in infoPagador

expiresIn
number

Expires the charge in seconds (minimum is 15 minutes)

expiresDate
string

Expiration date of the charge. Only in ISO 8601 format.

object or object or object (CustomerPayload)

Customer field is not required. However, if you decide to send it, you must send at least one of the following combinations, name + taxID or name + email or name + phone.

daysForDueDate
number

Time in days until the charge hits the deadline so fines and interests start applying. This property is only considered for charges of type OVERDUE

daysAfterDueDate
number

Time in days that a charge is still payable after the deadline. This property is only considered for charges of type OVERDUE

object

Interests configuration. This property is only considered for charges of type OVERDUE

object

Fines configuration. This property is only considered for charges of type OVERDUE

object

Discount settings for the charge. This property is only considered for charges of type OVERDUE

Array of objects

Additional info of the charge

enableCashbackPercentage
boolean

true to enable cashback and false to disable.

enableCashbackExclusivePercentage
boolean

true to enable fidelity cashback and false to disable.

subaccount
string

Pix key of the subaccount to receive the charge

Array of objects

This is the array that will configure how will be splitted the value of the charge

Responses

Request samples

Content type
application/json
Example
{
  • "correlationID": "9134e286-6f71-427a-bf00-241681624587",
  • "value": 100,
  • "comment": "good",
  • "customer": {
    },
  • "additionalInfo": [
    ]
}

Response samples

Content type
application/json
{
  • "charge": {
    }
}

charge refund

Endpoint to manage charge refunds

Get all refunds of a charge

Endpoint to get all refunds of a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • cf4012c9-b2ac-484d-8121-deedd1c6d8af -
  • fe7834b4060c488a9b0f89811be5f5cf -

The correlation ID of the charge. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create a new refund for a charge

Endpoint to create a new refund for a charge

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • cf4012c9-b2ac-484d-8121-deedd1c6d8af -
  • fe7834b4060c488a9b0f89811be5f5cf -

The correlation ID of the charge. You will need URI encoding if your correlation ID has characters outside the ASCII set or reserved characters (%, #, /).

Request Body schema: application/json
required

Data to create a new refund for a charge

correlationID
required
string

Your correlation ID to keep track for this refund

value
number

Value in cents for this refund

comment
string <= 140

Comment for this refund. Maximum length of 140 characters.

Responses

Request samples

Content type
application/json
{
  • "correlationID": "a273e72c-9547-4c75-a213-3b0a2735b8d5",
  • "value": 100,
  • "comment": "Comentário do reembolso"
}

Response samples

Content type
application/json
{
  • "refund": {
    }
}

customer

Endpoint to manage Customer

Get one customer

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

correlation ID

Responses

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Get a list of customers

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "customers": {
    }
}

Create a new Customer

Endpoint to create a new Customer

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new customer

One of
name
required
string
email
string
phone
string
taxID
required
string
correlationID
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "Dan",
  • "taxID": "31324227036",
  • "email": "email0@example.com",
  • "phone": "5511999999999",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Update a Customer

Endpoint to update a Customer

Authorizations:
AppID
path Parameters
correlationID
required
string
Examples:
  • fe7834b4060c488a9b0f89811be5f5cf -

correlation ID

Request Body schema: application/json
required

Data to update a existent customer

name
string
email
string
phone
string
taxID
string
object

Responses

Request samples

Content type
application/json
{
  • "name": "Dan",
  • "email": "email0@example.com",
  • "phone": "5511999999999",
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

partner (request access)

Partners integrate affiliated companies.
They can register new companies, manage them, and earn money from them.

Create a new application to some of your preregistration's company.

As a partner company, you can create a new application to some of your companies. The application should give access to our API to this companies, so they can use it too.

Authorizations:
AppID
Request Body schema: application/json
required

The request body to create a pre registration.

object
object (TaxIDObjectPayload)

Responses

Request samples

Content type
application/json
{
  • "application": {
    },
  • "taxID": {
    }
}

Response samples

Content type
application/json
{
  • "application": {
    }
}

Get an specific preregistration via taxID param.

Authorizations:
AppID
path Parameters
taxID
required
string
Examples:
  • 60151449000182 -

The raw tax ID from the preregistration that you want to get.

Responses

Response samples

Content type
application/json
{
  • "preRegistration": {
    }
}

Get every preregistration that is managed by you.

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "preRegistrations": [
    ],
  • "pageInfo": {
    }
}

Create a pre registration with a partner reference (your company)

As a partner company, you can create a new pre registration referencing your company as a partner.

Authorizations:
AppID
Request Body schema: application/json
required

The request body to create a pre registration.

object (PreRegistrationObject)
object (PreRegistrationUserObject)

Responses

Request samples

Content type
application/json
{
  • "preRegistration": {
    },
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "preRegistration": {
    },
  • "user": {
    }
}

payment (request access)

Endpoint to init a payment using a Pix Key.

Approve a Payment Request

Endpoint to approve a payment

Authorizations:
AppID
Request Body schema: application/json
required

Data to approve a payment request

correlationID
string

the correlation ID of the payment to be approved

Responses

Request samples

Content type
application/json
{
  • "correlationID": "payment1"
}

Response samples

Content type
application/json
{
  • "payment": {
    },
  • "transaction": {
    },
  • "destination": {
    }
}

Get one Payment

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

payment ID or correlation ID

Responses

Response samples

Content type
application/json
{
  • "payment": {
    },
  • "transaction": {
    },
  • "destination": {
    }
}

Get a list of payments

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "payments": {
    }
}

Create a Payment Request

Endpoint to request a payment

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a payment request

One of
value
required
number

value of the requested payment in cents

destinationAlias
required
string

the pix key the payment should be sent to

destinationAliasType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

the type of the pix key the payment should be sent to

correlationID
required
string

an unique identifier for your payment

comment
string

the comment that will be send alongisde your payment

Responses

Request samples

Content type
application/json
Example
{
  • "value": 100,
  • "destinationAlias": "c4249323-b4ca-43f2-8139-8232aab09b93",
  • "destinationAliasType": "RANDOM",
  • "comment": "payment comment",
  • "correlationID": "payment1"
}

Response samples

Content type
application/json
Example
{
  • "payment": {
    }
}

pixQrCode

Endpoint to manage static QRCodes

Get one Pix QrCode

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -
  • zr7833b4060c488a9b0f89811 -

pixQrCode ID, correlation ID or emv identifier

Responses

Response samples

Content type
application/json
{}

Get a list of Pix QrCodes

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "pixQrCodes": {}
}

Create a new Pix QrCode Static

Endpoint to create a new Pix QrCode Static

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new Pix QrCode Static

name
required
string

Name of this pix qrcode

correlationID
string

Your correlation ID to keep track of this qrcode

value
number

Value in cents of this qrcode

comment
string

Comment to be added in infoPagador

Responses

Request samples

Content type
application/json
{
  • "name": "my-qr-code",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "value": 100,
  • "comment": "good"
}

Response samples

Content type
application/json
{}

transactions

Endpoint to manage Transactions

Get a Transaction

Authorizations:
AppID
path Parameters
id
required
string

you can use the transaction id from openpix or the endToEndId of transaction from bank

Responses

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

Get a list of transactions

Authorizations:
AppID
query Parameters
start
string <date-time> (Start Date)
Example: start=2020-01-01T00:00:00Z

Start date used in the query. Complies with RFC 3339.

end
string <date-time> (End Date)
Example: end=2020-12-01T17:00:00Z

End date used in the query. Complies with RFC 3339.

charge
string
Example: charge=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA

You can use the charge ID or correlation ID or transaction ID of charge to get a list of transactions related of this transaction

pixQrCode
string
Example: pixQrCode=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA

You can use the QrCode static ID or correlation ID or identifier field of QrCode static to get a list of QrCode related of this transaction

withdrawal
string
Example: withdrawal=Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA

You can use the ID or EndToEndId of a withdrawal transaction to get all transactions related to the withdrawal

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "transactions": {
    }
}

refund

Endpoint to manage Refunds

Get one refund

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

refund ID or correlation ID

Responses

Response samples

Content type
application/json
{
  • "pixTransactionRefund": {
    }
}

Get a list of refunds

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "refunds": [
    ]
}

Create a new refund

Endpoint to create a new refund for a customer

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new refund

value
number
transactionEndToEndId
string

Your transaction ID, or endToEnd ID, to keep track of this refund

correlationID
string

Your correlation ID, unique identifier refund

comment
string <= 140

Comment of this refund. Maximum length of 140 characters.

Responses

Request samples

Content type
application/json
{
  • "transactionEndToEndId": "9134e286-6f71-427a-bf00-241681624586",
  • "correlationID": "9134e286-6f71-427a-bf00-241681624586",
  • "value": 100,
  • "comment": "Comentário do reembolso"
}

Response samples

Content type
application/json
{
  • "refund": {
    }
}

sub account (request access)

Endpoint to manage sub accounts.

Withdraw from a Sub Account

Withdraw from a Sub Account and return the withdrawal transaction information

Authorizations:
AppID
path Parameters
id
required
string
Example: destination@test.com

pix key registered to the subaccount

Responses

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

Get subaccount details

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • c4249323-b4ca-43f2-8139-8232aab09b93 -

pix key registered to the subaccount

Responses

Response samples

Content type
application/json
{
  • "SubAccount": {
    }
}

Get a list of subaccounts

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "subAccounts": [
    ],
  • "pageInfo": {
    }
}

Create a subaccount

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new subAccount or retrieve existing one

pixKey
string

The pix key for the sub account

name
string

Name of the sub account

Responses

Request samples

Content type
application/json
{
  • "pixKey": "9134e286-6f71-427a-bf00-241681624587",
  • "name": "Test Account"
}

Response samples

Content type
application/json
{
  • "SubAccount": {
    }
}

Transfer between subaccounts

Transfer between subaccounts

Authorizations:
AppID
Request Body schema: application/json
required

Data to make a new transfer between subaccounts

value
required
number

The value of the transfer in cents

fromPixKey
required
string

The transfer origin pix key

fromPixKeyType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

The transfer origin pix key type

toPixKey
required
string

The transfer destination pix key

toPixKeyType
required
string
Enum: "CPF" "CNPJ" "EMAIL" "PHONE" "RANDOM"

The transfer destination pix key type

correlationID
string

Your correlation ID to keep track of this transfer

Responses

Request samples

Content type
application/json
{
  • "value": 65,
  • "fromPixKey": "c4249323-b4ca-43f2-8139-874baab09b93",
  • "fromPixKeyType": "RANDOM",
  • "toPixKey": "3143da48-2bc7-49a4-89bd-4e22f73bfb0c",
  • "toPixKeyType": "RANDOM"
}

Response samples

Content type
application/json
{
  • "value": 65,
  • "destinationSubaccount": {
    },
  • "originSubaccount": {
    }
}

subscription

Endpoint to manage Subscriptions

Get one subscription

Authorizations:
AppID
path Parameters
id
required
string
Example: UGF5bWVudFN1YnNjcmlwdGlvbjo2M2UzYjJiNzczZDNkOTNiY2RkMzI5OTM=

The globalID or correlationID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Create a new Subscription

Endpoint to create a new Subcription

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new Subscription

required
object

Customer of this subscription

value
required
number

Value in cents of this subscription

comment
string

Comment to be added in infoPagador

Array of objects

Additional info of the charge

dayGenerateCharge
number [ 1 .. 31 ]
Default: 5

Day of the month that the charges will be generated. Maximum of 31.

frequency
string
Enum: "WEEKLY" "MONTHLY" "BIMONTHLY" "TRIMONTHLY" "SEMIANNUALY" "ANNUALY"

Frequency of the subscription

chargeType
string
Default: "DYNAMIC"
Enum: "DYNAMIC" "OVERDUE"

The charge type is used to determine whether charges generated by the subscription will have fines and interests

dayDue
number >= 3
Default: 7

Days that the charge will take to expire from the generation day.

correlationID
required
string

Your correlation ID to keep track of this subscription

Responses

Request samples

Content type
application/json
Example
{
  • "value": 100,
  • "customer": {
    },
  • "dayGenerateCharge": 15
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

transfer (request access)

Endpoint to transfer values between accounts.

Create a Transfer

Endpoint to to transfer values between accounts

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a transfer

value
number

value of the transfer in cents

fromPixKey
string

the pix key of the account the value of the transfer will come out from

toPixKey
string

the pix key of the account the value of the transfer will go to

Responses

Request samples

Content type
application/json
{
  • "value": 100,
  • "fromPixKey": "from@openpix.com.br",
  • "toPixKey": "to@openpix.com.br"
}

Response samples

Content type
application/json
{
  • "transaction": {
    }
}

webhook

Endpoint to manage Webhooks

Delete a Webhook

Endpoint to delete a Webhook

Authorizations:
AppID
path Parameters
id
required
string
Examples:
  • Q2hhcmdlOjYwM2U3NDlhNDI1NjAyYmJiZjRlN2JlZA== -
  • fe7834b4060c488a9b0f89811be5f5cf -

webhook ID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get a list of webhooks

Authorizations:
AppID
query Parameters
url
string
Example: url=https://mycompany.com.br/webhook

You can use the url to filter all webhooks

Responses

Response samples

Content type
application/json
{
  • "pageInfo": {
    },
  • "webhooks": [
    ]
}

Create a new Webhook

Endpoint to create a new Webhook

Authorizations:
AppID
Request Body schema: application/json
required

Data to create a new webhook

object (WebhookPayload)
name
string
event
string (WebhookEventEnum)
Enum: "OPENPIX:CHARGE_CREATED" "OPENPIX:CHARGE_COMPLETED" "OPENPIX:CHARGE_EXPIRED" "OPENPIX:TRANSACTION_RECEIVED" "OPENPIX:TRANSACTION_REFUND_RECEIVED" "OPENPIX:MOVEMENT_CONFIRMED" "OPENPIX:MOVEMENT_FAILED" "OPENPIX:MOVEMENT_REMOVED"

Available events to register a webhook to listen to. If no one selected anyone the default event will be OPENPIX:TRANSACTION_RECEIVED.

  • OPENPIX:CHARGE_CREATED - New charge created
  • OPENPIX:CHARGE_COMPLETED - Charge completed is when a charge is fully paid
  • OPENPIX:CHARGE_EXPIRED - Charge expired is when a charge is not fully paid and expired
  • OPENPIX:TRANSACTION_RECEIVED - New PIX transaction received
  • OPENPIX:TRANSACTION_REFUND_RECEIVED - New PIX transaction refund received or refunded
  • OPENPIX:MOVEMENT_CONFIRMED - Payment confirmed is when the pix transaction related to the payment gets confirmed
  • OPENPIX:MOVEMENT_FAILED - Payment failed is when the payment gets approved and a error occurs
  • OPENPIX:MOVEMENT_REMOVED - Payment was removed by a user
url
string
authorization
string
isActive
boolean

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

Callback payload samples

Callback
Content type
application/json
{
  • "charge": {
    },
  • "pix": {
    },
  • "pixQrCode": null
}

Get a list of webhook IPs

Authorizations:
AppID

Responses

Response samples

Content type
application/json
{
  • "ips": [
    ]
}