Version: current

Create a Pix

About this guide

This guide quickly demonstrates how to create a pix in EBANX. We will walk you through the basic steps to achieve this goal using your already existing Direct API integration.

How it works

To create a pix through EBANX Direct API, please follow the steps below.

  1. Make sure you have all the mandatory fields in your request

    There are a few key parameters you need to provide to create a pix. Check the table below for more details.

    FieldDescription
    integration_keyYour unique and secret integration key.
    external_referenceThe unique pix ID provided by you.
    countryTwo letters, reference to Brazil (br)
    amountThe amount in the specified currency (currency_code).
    currency_codeThree-letter code of the payout currency. Right now, the pix currency_code is available only to BRL (Brazil)
    targetThe type of operation.
    - pix: when the payee provides the bank account information
    - pix_key: when the payee provides the pix key (CPF, CNPJ, random key, email or phone number)
    target_accountThe key to send the pix. These keys can be used:
    - CPF: 12345678901 (Brazilian Individual Taxpayer Registry Identification number, with eleven digits)
    - CNPJ: 12345678901234 (Brazilian Legal Entities Registry number, with fourteen digits)
    - Email
    - Mobile phone number: +5501234567890
    - random (thirty-two alphanumeric digits)
    payeeA JSON object containing the details of the payee of your request.
    Payee Details

    Note that you can either provide all the information of the payee directly on your pix creation request or create the payee record in advance, using the /ws/payee/create endpoint, and simply provide the payee's document number in the payout request.

    Document Types Allowed:

    These types of documents are used by the payees or shareholders.

    Document typeDescription
    CPFThe CPF is a document with an 11 digits number.
    CNPJThe CNPJ is a document with a 14 digits number that identifies a company.

  2. Send your pix request to EBANX

    To create a new Pix, you will use the /ws/payout/create endpoint.

    There are two ways to identify the payee with pix.

    1 - Pix using bank info account

    The following example is a pix create request to send a pix to some payee, using the bank account info:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'country=br' \
    -d 'amount=10' \
    -d 'currency_code=BRL' \
    -d 'target=pix' \
    -d 'payee[document]=08432961781' \
    -d 'payee[document_type]=CPF' \
    -d 'payee[name]=Carlos Machado' \
    -d 'payee[email]=carlos_machado_pix@gmail.com' \
    -d 'payee[bank_info][bank_name]=104 Caixa Econômica' \
    -d 'payee[bank_info][bank_branch]=3708' \
    -d 'payee[bank_info][bank_account]=08251777-6' \
    -d 'payee[bank_info][account_type]=C' \
    -d 'payee[bank_info][bank_details]=001' \
    -d 'payee[bank_info][bank_ispb]=00360305' \

    You can choose between bank_ispb or bank_name, we recommend that you send just one.

    And a successful creation will return a JSON Object with type "success" and a pix object with all the details of the newly created Pix.

    {
    "integration_key":"your_integration_key",
    "external_reference":"teste_mass_prod_2",
    "country":"br",
    "amount":"10",
    "currency_code":"BRL",
    "use_payee_hub":false,
    "payee":{
    "document":"08432961781",
    "document_type":"cpf",
    "name":"Carlos Machado",
    "email":"carlos_machado_pix@gmail.com",
    "birthdate": null,
    "bank_info":{
    "bank_name": "104 Caixa Economica",
    "bank_branch": "3708",
    "bank_account": "8251777-6",
    "account_type": "C",
    "bank_details": "001",
    "bank_ispb": "00360305"
    },
    "address":{
    "zipcode":"80010-010",
    "state":"PR",
    "city":"Curitiba",
    "street_address":"Rua Marechal Deodoro",
    "street_complement":"630"
    }
    },
    "target":"pix"
    }

    2 - Pix using a pix_key

    The pix key is a unique code associated to the payee's account. (See target_account for different options of keys)

    curl -X POST 'https://sandbox.ebanxpay.com/ws/payout/create' \
    -d 'integration_key=your_test_integration_key' \
    -d 'external_reference=PAYOUT_EBANX_04' \
    -d 'country=br' \
    -d 'amount=10' \
    -d 'currency_code=BRL' \
    -d 'target=pix_key' \
    -d 'target_account=carlos_machado_pix@gmail.com' \
    -d 'payee[document]=08432961781' \
    -d 'payee[document_type]=CPF' \
    -d 'payee[name]=Carlos Machado' \
    -d 'payee[email]=carlos_machado_pix@gmail.com'

    And a successful creation will return a json similar to the one below:

    {
    "integration_key":"your_integration_key",
    "external_reference":"teste_mass_prod_2",
    "country":"br",
    "amount":"10",
    "currency_code":"BRL",
    "use_payee_hub":false,
    "payee":{
    "document":"08432961781",
    "document_type":"cpf",
    "name":"Carlos Machado",
    "email":"carlos_machado_pix@gmail.com",
    "birthdate":null,
    "address":{
    "zipcode":"80010-010",
    "state":"PR",
    "city":"Curitiba",
    "street_address":"Rua Marechal Deodoro",
    "street_complement":"630"
    }
    },
    "target":"pix_key",
    "target_account":"carlos_machado_pix@gmail.com"
    }

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Edit this page
Last updated on by Matheus Aeroso
On this page