Pix-out transfer

post

https://sandbox-cdn.pismolabs.io/pix/v1/pix/out/transfer

Perform a Pix-out transfer.

If you are using a key or QR Code, you need to call Validate DICT key or Get and validate QR Code 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 Pix-out notification received event and a Pix reconciliation notification received event.

This endpoint also generates a Pix-in notification received 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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request Body

account_id

integer

required

Pismo account ID.

amount

number

required

Amount to be transferred.

bank_account

object

required

Payer's bank account details.

initiation_type

string

enum

required

length ≤ 20

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 Open Finance 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.

ispb

string

required

length ≤ 8

ISPB (Identifcador do Sistema de Pagamento Brazil) - the Brazilian Payment System ID, an 8-digit value.

payee

object

required

Payee's information. The payee is the transfer receipient.

transaction_type

string

enum

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)

Allowed:

charges

object

Charges details. REQUIRED if returned from QR Code validation.

debtor

object

Debtor information. The debtor could be the payer, or someone who made a purchase on the payer's behalf.

end_to_end_id

string

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:

Initialize a transaction
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_registered

boolean

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

initial_amount

string

The initial purchase price amount before charges or withdrawal changes.

initiator_document_number

string

length ≤ 14

Payment initiator document number when type is PAYMENT_INITIATOR

payment_type

string

enum

Payment type.

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

Allowed:

psp_account

object

Payment service provider (PSP) information. This object is REQUIRED if transaction_type = REFUND.

transaction_identification

string

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.

metadata

object

Key-value fields for adding custom information to request. Total maximum object size = 3000 bytes.

qr_code_additional_information

array of objects

Additional QR Code information.

qr_code_additional_information

remittance_information

string

length ≤ 140

Text payer wents to send to payment receiver.

urgency

string

enum

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

Allowed:

withdrawal

object

Withdrawal details. For QR codes and CHANGE and WITHDRAWAL transactions. For example: a customer goes to a shop, makes a purchase, and also asks for cash back.

psp_transaction_created_at

string

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

signature_info

object

Signature information, including the digital signature over the request data that <a href="https://www.legislation.gov.uk/ukpga/2022/46/contents" that a PSTI validates. A Prestadores de Serviços de Tecnologia da Informação (PSTI) - Information and Technology Service Provider in English — is a technology service provider that connects to the banking/financial infrastructure (specifically the Rede do Sistema Financeiro Nacional – RSFN) on participants' behalf.

The signature here is the digital signature standard using a private asymmetric key (RSA or Elliptic Curve) over an input buffer extracted from the request and provider-defined.

This field guarantees the request's integrity and authenticity and the transaction messaging non-repudiation (assurance that a party involved in a transaction cannot later deny their involvement) from customer to PSTI.

For more information, refer to the Scheduled Pix-out transfer encryption guide.

Note: Customers should contact the PSTI to get more information about the encryption process and how to store the certificate related to the certificate thumbprint. Pismo acts as a pass-through entity in this process.

Headers

Authorization

string

required

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

Idempotency-Key

string

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.

Responses

Pix-out transfer

Changelog

Support

Pismo is here to help

202Response Body

400Bad Request

403Forbidden

404Not Found

409Conflict

429Too Many Requests

500Internal Server Error

502Bad Gateway

504Gateway Timeout