The pix-api provides endpoints for transactional operations, including:

• Pix-in — Deposit funds to the platform account from an external environment.
  • Inbound notification — Validate Pix-in information before performing the cash-in process.
  • Reversal (refund) — Reverse a completed transaction.
• Pix-out — Withdraw funds from the platform account to an external environment.
  • QR code validation — Exchange and validate a QR code as part of a transaction.
  • Transfer — Acknowledge and complete the transfer of funds.

In addition, there are two types of funds transfer (both of which are handled by the Pix-out API):

• Internal transfer: When the payee and payer are in the same Org, an internal endpoint does a peer-to-peer transaction.
• External transfer: When the payee and payer are from different Orgs or from outside of Pismo, an external endpoint executes the transaction.

end_to_end_id

The end_to_end_id is a unique ID assigned to every Pix transaction. It is created when the client validates a key or a QR code, and the same value is used throughout the transaction process. This ID cannot be changed.

Sending and receiving a payment

The client starts an outbound Pix payment using the endpoint Perform a pix-out transfer. However, the transaction confirmation is asynchronous and uses a webhook. Upon completion, the platform generates an event with status SETTLED (successful transaction) or CANCELLED (failed transaction) to the client.

Event

{
	"event_id": "cid",
	"cid": "cid",
	"timestamp": "",
	"org_id": "org",
	"domain": "pix",
	"event_type": "pix_out",
	"schema_version": "1",
	"data": {
		"account_id": 123,
		"authorization_id": 123,
		"end_to_end_id": "E0000000020210519134701363533333",
		"amount": 123.50,
		"status": "SETTLED",
		"reason": "",
		"payee_name": "Fulado de Tal",
		"payee_participant": "12345678"
	}
}

Scheduled transactions

Users can schedule Pix transactions for a future date. Basically the user specifies a future date to make the payment, along with the transaction details, such as the payee (branch and account) and transaction amount. You should call the scheduling endpoint instead of the payment-execution endpoint, and the payment effectuation will be performed by Pismo on the scheduled date.

The BCB does not stipulate a scheduling date, so it is not necessary to set a limit for the scheduling date and time. However, key validation fails if the payment date is different from the current date.

Schedule a Pix-out

Perform a scheduled transfer

Request

{
  "schedule_datetime": "2021-12-10T12:34:56.000Z",
  "account_id": 123,
  "ispb": "123456", 
  "bank_account": {  
    "branch": "500",  
    "account_number": "123",  
    "account_type": "456"  
  },
  "initiation_type": "MANUAL", 
  "payee": {  
    "bank": "",  
    "account_number": "", 
    "branch": "",  
    "document_number": "", 
    "account_type": "", 
    "name": "",  
    "key": "" 
  },
  "amount": 115.00,  
  "end_to_end_id": "E3030629420200808195101608910248", //optional
  "remittance_information": "Obs.." //optional
}

Response

{
  "schedule_id": "9cfa0a86-491f-4fe6-8efc-fd35476fd5ee",
  "end_to_end_id": "E3030629420200808195101608910248",
  "schedule_datetime": "2021-12-10T12:34:56.000Z",
  "schedule_creation_datetime": "2021-11-10T12:34:56.000Z",
  "status": "SCHEDULED",
  "amount": 115.00,
  "payee": {
    "name": "Fulano",
    "document_number": "",
    "ispb": ""
  },
  "payer": {
    "name": "Beltrano",
    "document_number": "",
    "ispb": ""
  }
}

Response

{
  "code": "EPIX0001",
  "details": "Details about the specific error",
  "message": "Some error message"
}

List scheduled Pix-outs

Get an account's scheduled transfers information

Request
No Body

{
  "page": 1,
  "current_page": 10,
  "per_page": 10,
  "total_items": 45,
  "items": [
    {
      "schedule_id": "9cfa0a86-491f-4fe6-8efc-fd35476fd5ee",
      "end_to_end_id": "E3030629420200808195101608910248",
      "schedule_datetime": "2021-12-10T12:34:56.000Z",
      "schedule_creation_datetime": "2021-11-10T12:34:56.000Z",
      "cancel_datetime": "", //if status == CANCELLED
      "amount": 115.00,
      "status": "SETTLED",
      "payee": {
        "name": "Fulano",
        "document_number": "",
        "ispb": "" //participant
      }
    }
  ]
}

Cancel Scheduled Pix-out

Cancel a scheduled transfer

Request
No Body

Reversal (Making and receiving a refund)

When you receive a Pix, you can return some or all of the amount received to the payer. This process is called reversal. Executing the reversal in our business context is a pix-out, because it is a return of a pix-in.

📘

A reversal is always initiated by the payee of the original transaction. The payer in the original transaction can request a reversal by sending an infraction report.