Version: current

PISP with Direct API

Overview

This guide will walk you through a basic API integration that accepts payments via PISP in EBANX.

note

PISP, Pix as Payment Initiator, is a feature of Pix with Open Finance. For this, Pix is offered by EBANX Instituição de Pagamento, which is a direct participant of the instant payment arrangement as specified in the Resolution nº1 of the Brazilian Central Bank.

About this guide

By following this basic integration guide, you will understand how you can accept PISP payments in your check-out, by using EBANX Direct API. To complete a payment with PISP you will need a single API call that will create the payment and provide the necessary information for the customer to complete the transaction.

Availability

PISP integration through Direct API is available in Brazil only.

What you will need

A Sandbox Account

As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.

Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!

Sign up for an EBANX Sandbox Account here

How it works

To complete a PISP payment, please follow the steps below.

  1. Enable PISP in your dashboard

    The first step is to check if PISP are active in your EBANX Dashboard.

    All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.

  2. Call the /ws/direct API

    PISP provides the option of redirecting the customer to their bank account. To get this link, you just need to call the end-point ws/direct (server-side) with the following required fields:

    • Operation: Must be request;
    • Payment type code: Must be pix-pisp;

    Customer data:

    • Customer name;
    • Customer e-mail;
    • Customer document;
    • Customer address;
    • Customer street number;
    • Customer city;
    • Customer state;
    • Customer zip-code;
    • Customer phone number

    Charge info:

    • Unique merchant payment code;
    • Currency code (BRL or USD);
    • Total amount to be charged;
    • PISP bank_id information;

    Check the example:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \
    -d 'request_body={
    "integration_key": "**************************3943d3",
    "operation": "request",
    "payment": {
    "name": "Jhon Snow",
    "email": "jhonSnow@example.com",
    "document": "764.041.200-54",
    "birth_date": "14\/04\/1970",
    "address": "Rua E",
    "street_number": "1040",
    "street_complement": "CJ 5",
    "city": "Maracanaú",
    "state": "CE",
    "zipcode": "61919-230",
    "country": "BR",
    "phone_number": "8522847035",
    "payment_typeintegration_key_code": "pix-pisp",
    "merchant_payment_code": "payment-for-pix-pisp",
    "currency_code": "BRL",
    "amount_total": 1,
    "pisp": {
    "bank_id": "b-756b9782-d9d4-4f9b-9756-997eba0e2cbd"
    }
    }
    }'

    A successful request will return a JSON response like the one below. The PISP redirect link will be in the parameter redirect_url.

    {
    "payment": {
    "hash": "6419fcbdc1a636ece0fb5038020a856c9f3e35169edebf00",
    "country": "br",
    "merchant_payment_code": "payment-for-pix-pisp",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2023-03-21 18:51:41",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "1.00",
    "amount_ext": "1.00",
    "amount_iof": "0.00",
    "amount_ext_requested": "1.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2023-03-24",
    "instalments": "1",
    "payment_type_code": "pix-pisp",
    "redirect_url": "https:\/\/api.ebanxpay.com\/ws\/redirect\/execute?hash=6419fcbdc1a636ece0fb5038020a856c9f3e35169edebf00",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
    "document": "76404120054",
    "email": "jhonSnow@example.com",
    "name": "JHON SNOW",
    "birth_date": "1998-04-14"
    },
    "single_transaction": {
    "amount_local": "0.00",
    "amount_crossborder": "1.00"
    }
    },
    "status": "SUCCESS",
    "redirect_url": "https:\/\/api.ebanxpay.com\/ws\/redirect\/execute?hash=6419fcbdc1a636ece0fb5038020a856c9f3e35169edebf00"
    }

    Params to use in Bank List

    In order to get the list of available bank institutions to use in bank_id parameter you just need to call the end-point ws/getBankList.

    curl --location --request GET 'https://api.ebanxpay.com/ws/getBankList?integration_key=**************************3943d3&payment_type=pix-pisp&country_code=br' \
    --header 'Content-Type: application/json'

    A successful request will return a JSON response like the one below. The available bank institutions with their unique bank_id in the parameter code.

    [
    {
    "code": "b-0bd96437-1521-4443-b5a4-92441cdf38cb",
    "name": "Banco ABC Brasil",
    "logo_url": "https://websto01.blob.core.windows.net/portaldodesenvolvedor/abc-logo.svg"
    },
    {
    "code": "b-d7e27a98-ef6c-4b79-b2d8-c2527eba8d84",
    "name": "Banco Inter PF",
    "logo_url": "https://d2ga2iknz0in5b.cloudfront.net/inter-logos/512.svg"
    },
    {
    "code": "b-c3463f74-87b3-40bd-8d40-2a918f821e31",
    "name": "Banco Original S.A",
    "logo_url": "https://www.original.com.br/img/logo-cubo-verde.svg"
    },
    {
    "code": "b-612da9a3-ee82-4f9e-9919-fa8ba88800f9",
    "name": "Banco PAN",
    "logo_url": "https://www.bancopan.com.br/data/files/83/77/FC/2A/5DE5A71033FBD5979C288204/logo_pan_openbanking.svg"
    },
    {
    "code": "b-aaacb9cf-e8c3-402b-93b8-cf4d3e2ec497",
    "name": "Banco Santander Pessoa Física",
    "logo_url": "https://cms.santander.com.br/sites/WPS/imagem/img-santander-chama/21-08-06_200409_P_santander_chama.svg"
    },
    {
    "code": "b-770f6211-dbd4-4c84-b6b1-9104b4a99359",
    "name": "Banco Santander Pessoa Jurídica",
    "logo_url": "https://cms.santander.com.br/sites/WPS/imagem/img-santander-chama/21-08-06_200409_P_santander_chama.svg"
    },
    {
    "code": "b-75db457a-612d-4d62-b557-ba9d32b05216",
    "name": "Banco do Brasil",
    "logo_url": "https://www.bb.com.br/docs/pub/inst/img/LogoBB.svg"
    },
    {
    "code": "b-88dc57a4-1dab-4493-8b02-b8f0c15a2d89",
    "name": "Banrisul",
    "logo_url": "https://banrisul.com.br/bob/data/Simbolo-Banrisul.svg"
    },
    {
    "code": "b-439a9b5c-2cfb-4e57-b60b-20eea83899ca",
    "name": "Bradesco Pessoa Física",
    "logo_url": "https://banco.bradesco/open-finance/logo/icones_vetorial-pf.svg"
    },
    {
    "code": "b-c6b15844-e748-4408-abb6-e71fd59d71c5",
    "name": "Bradesco Pessoa Jurídica",
    "logo_url": "https://banco.bradesco/open-finance/logo/icones_vetorial-pj.svg"
    },
    {
    "code": "b-221601a9-6e70-4698-9ea3-1bb28ceb4269",
    "name": "CAIXA",
    "logo_url": "https://consentimento.openbanking.caixa.gov.br/assets/images/logomarca_caixa.svg"
    },
    {
    "code": "b-9326f9b2-ae57-42c4-a0d9-acc4ba434696",
    "name": "Mercado Pago",
    "logo_url": "https://http2.mlstatic.com/frontend-assets/opb-logos/logo.svg"
    },
    {
    "code": "b-756b9782-d9d4-4f9b-9756-997eba0e2cbd",
    "name": "PicPay",
    "logo_url": "https://picpay.s3.sa-east-1.amazonaws.com/openbanking/picpay-logo-icon-pf.svg"
    },
    {
    "code": "b-be927760-d679-4c60-b5af-de2db2fa7bd6",
    "name": "PicPay Empresas",
    "logo_url": "https://picpay.s3.sa-east-1.amazonaws.com/openbanking/logo-picpay-empresas.svg"
    }
    ]
    note

    The complete API reference for the end-point ws/direct can be found here. We strongly recommend you to take a look in all the available options.

  3. Wait for the payment

    As soon as we get the confirmation, payment status is modified from pending (PE) to confirmed (CO).

    Important!

    Pix payments expire after 4 hours. If your customers don't complete the payment via pix in time, the payment will be automatically canceled.

Getting help

If you have any doubts or need help, you can send and email to: EBANX Integration

Last updated on by Gabriel Rodrigues