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.

endToEndId

The endToEndID 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 retried.

Sending and receiving a payment

The client starts an outbound Pix payment using the endpoint /v1/pix/out/transfer. However, the transaction confirmation is asynchronous and uses a webhook. Upon completion, the platform delivers 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.

There is no date for scheduling stipulated by the BCB, 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

POST /v1/pix/out/schedule

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 /v1/pix/out/accounts/{account_id}/schedules

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

POST /v1/pix/out/schedule/{id}/cancel

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.