Pix Integration through Pix Hub

Onboarding and transactional documentation.

API for Acceptance Terms

General Information

Introduction

This document is intended to facilitate integration with Fiserv's PSP Boarding API for capture acceptance terms, providing a flow overview and details of the new endpoints.

Environments

• Production: https://connect.latam.fiservapis.com/gateway
• Certification: https://connect-cert.latam.fiservapis.com/gateway

POST /v3/clients/opt-in

Endpoint that generates the link for acceptance terms.

{
  "document": {
    "type": "CNPJ",
    "number": "60.664.745/0001-87"
  },
  "tradeName": "Fiserv Inc",
  "pixFee": {
    "percentage": 100,
    "min": 0,
    "max": 5
  },
  "contact": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "5511999111000"
  }
}

{
  "url": "https://identify-hmg.stoneage.com.br/?token=HKenPEA-vW1o_oqQlJ7uH",
  "id": "557997d6-80db-4ab7-acd4-fe7753e8b76a"
}

GET /v3/clients/link/:link_id

Endpoint to check the status of terms acceptance.

{
  "document": {
    "type": "CNPJ",
    "number": "60664745000187"
  },
  "status": "FINISHED"
}

Pix Hub Onboarding

General Information

Introduction

This document is intended to facilitate integration with Fiserv's Pix Hub Onboarding API, providing an overview for managing account holders and stores. The main operations described are:

• Authentication: Generate the token and HMAC signature which are required for all requests.
• Store: Register, update, retrieve and delete stores.
• Webhook management: Register your webhook URL to receive notifications from the boarding process.
• Protocol: Retrieve protocol information.

Standard Headers

All requests require the following headers:

Async Processing

Depending on the operation, Pix Hub Onboarding will process requests either synchronously or asynchronously.

• Asynchronously: A unique protocol identification (UUID-v4) will be provided in the Pix Hub Onboarding response, along with an HTTP 202 – Accepted response.
• Synchronously: Expected HTTP 201 – Created or HTTP 200 – OK.

Error Format

All errors handled are returned in the following standard format:

{
  "type": "/error/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Status code indicates that the request could not be completed due to a conflict with the current state of the target resource",
  "instance": "/omnihub/onboard/v4/pix-gateway/stores",
  "properties": {
    "protocolId": "725040be-54f2-4546-9f6a-1f591fc60318",
    "additionalDetails": [
      {
        "errorCode": "409",
        "errorMessage": "Additional error information"
      }
    ],
    "timestamp": "2025-05-18T19:21:37.846642896Z"
  }
}

POST /token

Endpoint that generates an OAuth 2.0 bearer token required for all requests. A valid combination of username and password (or client_id and client_secret) are required.

See Authentication Documentation

HMAC Calculation

The HMAC signature must be calculated using a SHA256 script using the private key provided by Fiserv, containing the following concatenated string:

APIKEY + TIMESTAMP + REQUEST_BODY + URL_PATH

var CryptoJS = require("crypto-js");

function setHMACAuth(request) {
  const currentDate = new Date();
  var HMAC_KEY = pm.environment.get('hmacKey') || pm.collectionVariables.get('hmacKey');
  var requestId = generateUUID();
  const timestamp = currentDate.getTime().toString();
  var requestedPath = pm.variables.replaceIn(pm.request.url).getPath();
  // Remove the first '/' if exists.
  requestedPath = requestedPath.indexOf('/') == 0 ? requestedPath.substring(1) : requestedPath;
  var body = request.body == undefined ? "" : pm.variables.replaceIn(request.body.toString());
  var context = "onboard/sandbox";
  if (request.url.path == 'token') {
    context = "gateway";
  }
  var rawData = API_KEY + timestamp + body + '/' + context + '/' + requestedPath;
  var signedValue = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, HMAC_KEY).update(rawData).finalize();
  hashedStringRequest = CryptoJS.enc.Base64.stringify(signedValue);
  pm.request.headers.add({ key: "x-timestamp", value: timestamp });
  pm.request.headers.add({ key: "x-hmac-signature", value: hashedStringRequest });
  pm.request.headers.add({ key: "x-request-id", value: requestId });
}

function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

setHMACAuth(pm.request);

Protocol

GET /v4/protocol/{protocol-id}

Get all data from the given protocol ID.

Webhooks

Configure the webhook URL to receive notifications from async boarding processes. For every request that returns HTTP 202 – Accepted, Pix Hub Onboarding will process it asynchronously. All events generated will trigger the webhook.

PUT /v3/webhook

Register or update the webhook URL to receive notifications from the async boarding processes. An auth object can be provided for Pix Hub Onboarding to authenticate with the external URL before making the notification.

GET /v3/webhook

Retrieve current webhook settings.

DELETE /v3/webhook

Remove the current webhook configuration.

Webhook Callbacks

{
  "protocolId": "faae306f-4018-3d2a-941c-79df4414c5ea",
  "externalProtocolId": null,
  "protocolStatus": "PROCESSING",
  "eventStatus": "SUCCESS",
  "eventSource": "FEPAS_MODULE",
  "eventType": "CREATE_STORE_FEPAS",
  "responseCode": "FEPAS_00200",
  "description": "Store and client created successfully"
}

{
  "protocolId": "faae306f-4018-3d2a-941c-79df4414c5ea",
  "externalProtocolId": null,
  "protocolStatus": "SUCCESS",
  "eventStatus": "SUCCESS",
  "eventSource": "FEPAS_MODULE",
  "eventType": "UPDATE_STORE_PIX_ROUTE_FEPAS",
  "responseCode": "FEPAS_00200",
  "description": "Store Pix route updated successfully"
}

Pix Gateway

General Information

Key Concepts

• Account Holder: The CNPJ to which the registered Pix key belongs. Pix keys can be associated with the stores below them.
• Store: Multiple per CNPJ; can be associated only with 1 Account Holder. Uses credentials bound to it to perform transactions. Identified by a unique composite key: establishmentId + externalReferenceId.
• Credential: A unique identification given when registering a Pix key on the platform.

HATEOAS

Most Pix Gateway endpoints include a links property in the response for API discoverability. The exposed links may change in the future. For every endpoint documented, expect the links property to contain at least what is listed, but possibly more.

Environments

The Pix Gateway API uses a different base URL from the other Onboarding APIs:

• Production: https://connect.latam.fiservapis.com/onboard/api
• Certification: https://connect-cert.latam.fiservapis.com/onboard/api

GET /v4/pix-gateway/account-holders/{id}

Retrieve the given Account Holder information.

GET /v4/pix-gateway/account-holders/{id}/credentials

Retrieve the given Account Holder's credential information.

Stores

POST /v4/pix-gateway/stores

Creates the store for Pix operations in the Pix Gateway structure. In this endpoint, you need to inform the Account Holder and it is possible to create credentials and configure routing contingencies or balancing based on PSPs.

Note: It is not possible to create the same store twice, but it IS possible to use the same document for two stores. The externalReferenceId field must be unique for stores with the same legal document, including the blank string.

GET /v4/pix-gateway/stores/{id}

Retrieve the given Store data.

PATCH /v4/pix-gateway/stores/{id}

Partial update a Pix Gateway store. Only the fields sent in the request will be updated. Also used to create a new credential to be used in an existing store.

DELETE /v4/pix-gateway/store/{store-id}/credentials/{credential-id}

Unbinds the given credential from the given store, without deleting the credential.

Credentials

GET /v4/pix-gateway/credentials/{id}

Retrieve the given Credential data.

DELETE /v4/pix-gateway/credentials/{id}

Delete the given Credential.

PSP

GET /v4/pix-gateway/psps

Retrieve all available PSPs, optionally filtering by activity status. Example: /v4/pix-gateway/psps?status=I. If no filter parameter is provided, all PSPs will be listed.

GET /v4/pix-gateway/psps/{id}

Retrieve the given PSP information.

Pix Hub

General Information

This document specifies the Pix Hub API for transactional operations involving collections and payments via Pix. Key features include:

• Authentication: Obtaining a token for all operations.
• Generation of Pix Collections: Create Pix collections efficiently and securely.
• Pix Payment Consultation: Check the status and details of payments made via Pix.
• Return: Return payments via Pix efficiently.

Error Structure

All errors handled are returned in the following standard format:

{
  "message": "Error message",
  "details": [
    {
      "errorCode": 0,
      "error": "Description of the error"
    }
  ]
}

Default Headers

Some information is required in all requests:

POST /token

Authentication endpoint required for all calls. Get the authentication token through a client_secret and client_id. Send via application/x-www-form-urlencoded and use the Bearer token for subsequent requests.

See Authentication Documentation

HMAC Calculation

The HMAC must be calculated using the SHA256 algorithm and the private key provided by Fiserv, containing the following concatenated fields:

APIKEY + TIMESTAMP + REQUEST_BODY + URL_PATH

var CryptoJS = require("crypto-js");

function setHMACAuth(request) {
  const currentDate = new Date();
  var API_KEY = pm.collectionVariables.get('apikey');
  var SECRET = pm.collectionVariables.get('secret');
  var requestId = generateUUID();
  const timestamp = currentDate.getTime().toString();
  var rawData = API_KEY + timestamp + request.body.toString() + '/' + pm.request.url.path.toString().replaceAll(',', '/');
  var signedValue = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, SECRET).update(rawData).finalize();
  hashedStringRequest = CryptoJS.enc.Base64.stringify(signedValue);
  pm.request.headers.add({ key: "x-timestamp", value: timestamp });
  pm.request.headers.add({ key: "x-hmac-signature", value: hashedStringRequest });
  pm.request.headers.add({ key: "x-request-id", value: requestId });
}

function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

setHMACAuth(pm.request);

Charges (Collections)

POST /apm/pix/v1/charges

Create a Pix charge (QR Code).

GET /apm/pix/v1/charges/{tid}

Query a charge by transaction ID.

PUT /apm/pix/v1/charges/{tid}/refund

Request a reversal (chargeback) of the charge amount. Should only be used after the customer has already made the payment and the transaction is finalized.

Charges with Due Date (Pix COBV)

POST /apm/pix/v2/charges-duedate

Create a Pix charge with a due date (COBV format).

GET /apm/pix/v2/charges-duedate/{tid}

Query a Pix COBV charge by transaction ID.

PUT /apm/pix/v1/charges/{tid}/cancel

Cancel the QR Code of the generated charge. Use this to cancel before the customer makes the payment, or when the transaction status has not yet been returned. If the transaction has already been paid, a refund will be requested automatically.

Transaction Callback

After the payment is made or the QR Code expires, the registered URL will receive the following notification.

⚠️

For security reasons, when receiving a callback, validate the Api-Key and the Authorization (HMAC signature).

Api-Key + Client-Request-Id + Timestamp + RequestBody

const crypto = require('crypto');

function guid() {
  function s4() {
    return Math.floor((1 + Math.random()) * 0x10000).toString(16).substring(1);
  }
  return s4() + s4() + s4() + s4() + s4() + s4() + s4() + s4();
}

const apiKey = "API_KEY";
const secret = "SECRET";
const clientRequestId = guid();
const timeStamp = new Date().getTime();
const requestBody = JSON.stringify(request.data);
const rawSignature = apiKey + clientRequestId + timeStamp + requestBody;

const hmac = crypto.createHmac('sha256', secret);
hmac.update(rawSignature);
const computedHmac = hmac.digest('base64');

const headers = {
  "content-type": "application/json",
  "client-request-id": clientRequestId,
  "Api-Key": apiKey,
  "Timestamp": timeStamp,
  "Auth-Token-Type": "HMAC",
  "Authorization": computedHmac
};