PISP integration through EBANX Direct API | EBANX Developers Academy

Pix Payment Initiator (PISP) enables direct, bank-to-bank payments through a secure, API-based connection. By integrating PISP with the EBANX Direct API, merchants can offer customers a seamless and efficient payment experience where funds are directly debited from their bank account and transferred to the merchant’s account in real time. PISP works under Open Banking regulations, allowing merchants to initiate payments on behalf of customers once authorized, reducing transaction costs and improving security. This payment method is particularly useful for e-commerce and recurring payments, as it supports instant, secure transactions with low fees. In this guide, you’ll find step-by-step instructions to integrate PISP, covering authorization, transaction initiation, and response handling for a smooth, compliant payment flow.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See Direct API Guide for more info.

How it works

Set up API access with EBANX credentials.
Implement customer bank authorization, where they grant permission for payment(s).
Initiate payment request to EBANX with details.
Confirm payment status from EBANX response.

Instructions

Follow the steps below.

Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
SandboxProduction
https://sandbox.ebanx.com/ws/direct

Define parameters

PISP allows customers to be redirected directly to their bank for payment authorization. To obtain this link, make a call to the ws/direct endpoint with the following parameters:

Basic parameters.

Parameter	Description
`operation`	Set to `request`
`integration_key`	Your EBANX integration key
`payment_type_code`	Set to `pix-pisp`
`country`	Set to `br` for Brazil.

Customer data.

Parameter	Description
`name`	Customer name
`email`	Customer e-mail
`phone_number`	Customer phone number
`document`	Customer's valid document number
`street_number`	Customer street number
`address`	Customer address
`city`	Customer city
`state`	Customer two-letter state code
`zipcode`	Customer zip code

Payment info.

Parameter	Description
`merchant_payment_code`	Unique merchant payment code
`currency_code`	Supported values: `BRL` and `USD`
`amount_total`	Total amount to be charged
`pisp.bank_id`	PISP bank ID (See section Get Bank Codes below)

Sample request

Use the following example to initiate a request.

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "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_type_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"
      }
    }
  }'

Sample response

A successful request returns a response similar to the example below, with the PISP redirect link in the 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"
}

At this stage, the payment will appear as pending (PE) in your

EBANX Dashboard

Monitor payment for status changes
Notifications
- EBANX will send a notification whenever a payment status changes.
- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
- Learn more about Payment Notifications
Status
- After receiving a notification, retrieve the payment status.
- When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).
- PISP payments expire after 4 hours. If the customer doesn’t complete the payment, it will eventually change to cancelled (CA).
- Learn more about Retrieving Payment Status
Congratulations!
You have succesfully integrated PISP.
For more information, refer to the
Direct API reference guide

Get bank codes

This section supports steps 2 and 3 above.

To obtain a list of available bank institutions used in PISP payments, follow the instructions below.

Define parameters
Parameter Description
integration_key Your EBANX integration key
payment_type Set to pix-pisp
country_code Set to br for Brazil.

Parameter	Description
`integration_key`	Your EBANX integration key
`payment_type`	Set to `pix-pisp`
`country_code`	Set to `br` for Brazil.

Sample request

Use the ws/getBankList endpoint to initiate a request.

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

Sample response

A successful request returns a response (similar to the example below), listing the available banking institutions along with each institution’s unique bank_id in the code parameter.

// List of available bank institutions
[
    {
        "code": "b-0bd96437-1521-4443-b5a4-92441cdf38cb", // bank_id
        "name": "Banco ABC Brasil",
        "logo_url": "https://websto01.blob.core.windows.net/portaldodesenvolvedor/abc-logo.svg"
    },
    {
        "code": "b-d7e27a98-ef6c-4b79-b2d8-c2527eba8d84", // bank_id
        "name": "Banco Inter PF",
        "logo_url": "https://d2ga2iknz0in5b.cloudfront.net/inter-logos/512.svg"
    },
    {

       //  ...additional institutions

    },
    {
        "code": "b-756b9782-d9d4-4f9b-9756-997eba0e2cbd", // bank_id
        "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", // bank_id
        "name": "PicPay Empresas",
        "logo_url": "https://picpay.s3.sa-east-1.amazonaws.com/openbanking/logo-picpay-empresas.svg"
    }
]

Congratulations!
You have succesfully retrieved Available Bank Institutions.

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explore

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

PISP

Requirements​

How it works​

Instructions​

Select your environment

Define parameters

Basic parameters.​

Customer data.​

Payment info.​

Sample request

Sample response

Monitor payment for status changes

Congratulations!

Get bank codes​

Define parameters

Sample request

Sample response

Congratulations!

Resources​

Sample Cards

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Instructions

Basic parameters.

Customer data.

Payment info.

Get bank codes

Resources