Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Pix

Pix-out transfer

Perform a Pix-out transfer.

If you are using a key or QR Code, you need to call <a href="https://developers.pismo.io/pismo-docs/reference/post-v2-pix-keys-validate">Validate DICT key</a> or <a href="https://developers.pismo.io/pismo-docs/reference/post-qr-code">Get and validate QR Code</a> before calling this endpoint. You need to enter the end_to_end_id returned from those calls here. Validation and transaction need to occur within 10 seconds. If you are not using a key or QR Code, this endpoint generates and returns an end_to_end_id value you can use in other endpoints.

The end_to_end_id field is a Brazil Central Bank (BCB) requirement to track Pix transactions. Basically, there are two steps to a Pix transaction: 1. Initialize a transaction and 2. Confirm a transaction. The end_to_end_id is sent to the BCB in both steps in order to identify all transaction information.

This endpoint generates a <a href="https://developers.pismo.io/events/docs/pix-pix-out-1">Pix-out notification received</a> event and a <a href="https://developers.pismo.io/events/docs/pix-financial-reconciliation-1">Pix reconciliation notification received</a> event.

This endpoint also generates a <a href="https://developers.pismo.io/events/docs/pix-pix-in-1">Pix-in notification received</a> event when the funds are deposited in the payee's account, which can be a Pismo account or an external account.

For all events, the status or result field indicates operation success or failure.

For more information, see the Pix instant payments guide.

post/pix/v1/pix/out/transfer

Headers

Authorizationstring required
Example:Bearer eyJhbGci...IUzUx

Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.

Idempotency-Keystring required

A unique ID to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.

Request body

account_idinteger required

Account ID

amountnumber double required

Fee amount.

initiation_type'MANUAL' | 'DICT' | 'STATIC_QRCODE' | 'DYNAMIC_QRCODE' | 'PAYMENT_INITIATOR' | 'AUTOMATIC_PIX' | 'DYNAMIC_PROXIMITY_PIX' | 'STATIC_PROXIMITY_PIX' required

Initiation type:

MANUAL - Manually initiated. Key is not used - bank account, bank code, document number, and branch are used for identification.

DICT - Diretorio de Identificadores de Contas de Transacapo (Transaction accounts ID directory). Pix/DICT key is used for identification.

STATIC_QRCODE - Reusable code that contains only the data necessary to complete a transaction. When using static QR Code, the transaction amount must be provided manually.

DYNAMIC_QRCODE - The amount and other details for a dynamic code are included automatically.

PAYMENT_INITIATOR - Payment provider initiated. A payment initiator is a 3rd party that has obtained authorization from the Central Bank and has an <a href="https://www.bcb.gov.br/en/financialstability/open_finance" target="_blank">Open Finance</a> certification.

AUTOMATIC_PIX - Payment order initiated via automatic PIX.

DYNAMIC_PROXIMITY_PIX - Dynamic Near Field Communications (NFC) based initiation.

STATIC_PROXIMITY_PIX - Static NFC-based initiation.

ispbstring required

<a href="https://bank.codes/numero-do-banco/bank/banco-central-do-brasil/" target="_blank">ISPB (Identifcador do Sistema de Pagamento Brazil)</a> - the Brazilian Payment System ID, an 8-digit value.

transaction_type'TRANSFER' | 'CHANGE' | 'WITHDRAWAL' | 'REFUND_AUTOMATIC_PIX' | 'REFUND' required

Type of transaction the QR Code validation generates.

  • TRANSFER - Standard immediate transfer payment.
  • CHANGE - Occurs when the QR Code validation returns CHANGE. For example, the customer buys something and pays more than the product value to receive the difference in cash.
  • WITHDRAWAL - Occurs when the QR Code validation returns WITHDRAWAL with withdrawal object values.
  • REFUND_AUTOMATIC_PIX - Total or partial to the PSP payer user within the Automatic Pix MED (Pix return mechanism) scope (only when initiated by a MANUAL).
  • REFUND = Total or partial refund to the paying user within the scope of MED 2.0, when this refund occurs from the PI Account of the user's PSP who participated in the distribution chain of the resources of the original transaction (only when initiated by a MANUAL)
end_to_end_idstring

This field is a Brazil Central Bank (BCB) requirement to track all steps of Pix transactions. Basically, there are two steps to a Pix transaction:

  1. Initialize a transaction
  2. Confirm a transaction

The end_to_end_id is sent to the BCB in both steps in order to identify all transaction information. REQUIRED if you are using a Pix key or QR Code.

is_device_registeredboolean

Is device registered to do a Pix-out transfer? Default is true.

initial_amountstring

The initial purchase price amount before charges or withdrawal changes.

initiator_document_numberstring

Payment initiator document number when type is PAYMENT_INITIATOR

payment_type'IMMEDIATE' | 'FRAUD' | 'SCHEDULED'

Payment type.

  • IMMEDIATE - Immediate payment.
  • FRAUD - Payment due to suspected fraud.
  • SCHEDULED - Scheduled payment.
transaction_identificationstring

This field is returned from the Validate QR Code endpoint.

Transaction ID is REQUIRED when initiation_type is DYNAMIC_QRCODE and should not be passed otherwise. If a STATIC_QRCODE contains the transaction identification, it is also REQUIRED to pass it.

metadatastring

Any data object with key/value pairs. No limit on length.

Note: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to Get started with Pismo APIs.

remittance_informationstring

Text payer wents to send to payment receiver.

urgency'NORMAL' | 'HIGH'

REQUIRED when initiation_type = PAYMENT_INITIATOR. Must be NORMAL in this case. Default is HIGH.

psp_transaction_created_atstring

Datetime since the transaction was created on client-side.

Format = RFC 3339 Nano. For example - 2014-03-19T00:08.179780629-04:00.

REQUIRED when passing signature_info

processing_codestring

A 6-digit code that identifies the financial processing category for the transaction, used for accounting and routing purposes.

This field is optional. When not provided, Pismo automatically assigns a value managed internally. If you provide a custom value, you take full responsibility for its correctness — an invalid or mismatched code may cause processing or reconciliation failures.

Example request

{
  "account_id": 6912345,
  "amount": 215,
  "bank_account": {
    "account_number": "98765432",
    "account_type": "TRAN",
    "branch": "011"
  },
  "initiation_type": "DICT",
  "ispb": "60701190",
  "payee": {
    "account_number": "98765432",
    "account_type": "TRAN",
    "bank": "237",
    "branch": "011",
    "document_number": "7777888hh",
    "name": "Paul Bearer",
    "beneficiary_id": "97c96d96-9b87-404b-88e5-287f2b0e6e0a",
    "key": "email@email.com",
    "type": "NATURAL_PERSON"
  },
  "transaction_type": "TRANSFER",
  "charges": {
    "discount_value": 0.15,
    "interest_value": 20.15,
    "fine_value": 5.15,
    "settled_value": 10.15
  },
  "debtor": {
    "document_number": "7777888hh",
    "name": "Paul Bearer"
  },
  "end_to_end_id": "E3030629420200808195101608910248",
  "is_device_registered": true,
  "initial_amount": "10.02",
  "payment_type": "IMMEDIATE",
  "psp_account": {
    "account_number": "98765432",
    "account_type": "TRAN",
    "bank": "237",
    "branch": "011",
    "document_number": "7777888hh",
    "name": "Paul Bearer",
    "taxes": {
      "tax_identifier": "IS0435879820240605bcdb1fhn43a",
      "records": [
        {
          "tax_type": "IBS",
          "amount": 1050.44
        }
      ]
    }
  },
  "transaction_identification": "1a84daf6-a61b-4aba-919a-a9943db7102e",
  "metadata": "{ \"key\": \"value\"}",
  "qr_code_additional_information": [
    {
      "name": "Discount",
      "value": "Paying until the 5th, there will be a 10% discount"
    }
  ],
  "urgency": "HIGH",
  "withdrawal": {
    "agent_modality": "AGTEC",
    "amount": 101.11,
    "ispb_service_provider": "60701190",
    "purchase_amount": 101.11
  },
  "psp_transaction_created_at": "2014-03-19T00:08.179780629-04:00",
  "signature_info": {
    "algorithm": "RSA_PKCS1_SHA256",
    "certificate_thumbprint": "3a2b4c1b...",
    "signature": "MIIb2132b=="
  },
  "processing_code": "123456",
  "taxes": {
    "tax_identifier": "IS0435879820240605bcdb1fhn43a",
    "records": [
      {
        "tax_type": "IBS",
        "amount": 1050.44
      }
    ]
  }
}

Response

Response Body

amountnumber double required

Fee amount.

end_to_end_idstring required

This field is a Brazil Central Bank (BCB) requirement to track all steps of Pix transactions. Basically, there are two steps to a Pix transaction: 1. Initialize a transaction 2. Confirm a transaction The end_to_end_id is sent to the BCB in both steps in order to identify all transaction information.

payee_namestring required

name

payer_namestring required

name

status'PROCESSING' | 'VALIDATED' | 'SETTLED' | 'CANCELLED' | 'ERROR' required

Current transaction status:

  • VALIDATED - Payload was validated and sent to provider

  • PROCESSING - Waiting response from the provider

  • SETTLED - Transaction confirmed

  • CANCELLED - Transaction cancelled

  • ERROR - Transaction error during processing

Example response

{
  "amount": 215,
  "end_to_end_id": "E3030629420200808195101608910248",
  "payee_name": "Paul Bearer",
  "payer_name": "Paul Bearer",
  "status": "PROCESSING"
}