Pix Hub Onboarding

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
• Certification: https://connect-cert.latam.fiservapis.com

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"
}

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.