Sign in

v1

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

Register beneficiary

Register a new beneficiary with Pismo.

A newly-registerd beneficiary is not initially enabled and must be <a href="https://developers.pismo.io/pismo-docs/reference/post-intl-bank-accounts-v1-bank-accounts-beneficiaries-beneficiary-id-activate">activated</a> before use in transactions.

post/v1/beneficiaries

Headers

Authorizationstring required

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

Request body

account_codestring required

Beneficiary account code.

account_idinteger required

Account ID

namestring required

Beneficiary's first and last name.

regionstring required

ISO-3166 two letter country code. For example, BR=Brazil.

schema'BANKACCOUNT' | 'PIX' | 'DOCUMENTNUMBER' required

Beneficiary schema validation:

BANKACCOUNT - account_code contains a Brazilian account number (used in junction with the bank_code and branch fields)

PIX - account_code contains a valid Pix key. For more information, see <a href="https://developers.pismo.io/pismo-docs/docs/pix-instant-payments" target="_blank">Pix instant payments</a>

DOCUMENTNUMBER - account_code contains a valid Brazilian document number. This is government document number, such as Cadastro de Pessoas Físicas number - a Brazilian tax registry number, similar to a Social Security number in the US.

account_type'CACC' | 'SLRY' | 'SVGS' | 'TRAN'

Account type:
CACC - Checking/current account. Known as "conta corrente" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. SVGS - Savings account TRAN - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments. SLRY - Salary account. Employer deposits a fixed amount every month.

aliasstring

Beneficiary alias.

bank_codestring

Beneficiary bank code.

branchstring

Beneficiary branch.

document_numberstring

A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil).

Example request

{
  "account_code": "7654321",
  "account_id": 78123456,
  "name": "Al Freydough",
  "region": "BR",
  "schema": "PIX",
  "account_type": "TRAN",
  "alias": "Curveball",
  "bank_code": "1086",
  "branch": "5555555",
  "document_number": "123412341234"
}

Response

Register beneficiary response body

account_codestring

Beneficiary account code.

account_idinteger

Account ID

account_type'CACC' | 'SLRY' | 'SVGS' | 'TRAN'

Account type:
CACC - Checking/current account. Known as "conta corrente" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. SVGS - Savings account TRAN - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments. SLRY - Salary account. Employer deposits a fixed amount every month.

aliasstring

Beneficiary alias.

bank_codestring

Beneficiary bank code.

beneficiary_idstring

UUID identifying beneficiary.

branchstring

Beneficiary branch.

creation_datetimestring date-time

Account creation date time displayed in ISO 8601 format 2023-04-12T23:20:50.52Z.

document_numberstring

A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil).

enabledboolean

Is beneficiary active flag.

namestring

Beneficiary's first and last name.

regionstring

ISO-3166 two letter country code. For example, BR=Brazil.

schema'BANKACCOUNT' | 'PIX' | 'DOCUMENTNUMBER'

Beneficiary schema validation:

BANKACCOUNT - account_code contains a Brazilian account number (used in junction with the bank_code and branch fields)

PIX - account_code contains a valid Pix key. For more information, see <a href="https://developers.pismo.io/pismo-docs/docs/pix-instant-payments" target="_blank">Pix instant payments</a>

DOCUMENTNUMBER - account_code contains a valid Brazilian document number. This is government document number, such as Cadastro de Pessoas Físicas number - a Brazilian tax registry number, similar to a Social Security number in the US.

updated_datetimestring date-time

Updated date time. A RFC 3339 value, i.e., "2023-04-12T23:20:50.52Z".

Example response

{
  "account_code": "7654321",
  "account_id": 78123456,
  "account_type": "TRAN",
  "alias": "Curveball",
  "bank_code": "1086",
  "beneficiary_id": "123e4567-e89b-12d3-a456-42661417",
  "branch": "5555555",
  "creation_datetime": "2023-04-12T23:20:50.52Z",
  "document_number": "123412341234",
  "enabled": true,
  "name": "Al Freydough",
  "region": "BR",
  "schema": "PIX",
  "updated_datetime": "2023-04-12T23:20:50.52Z"
}