Pix Hub Transaction

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.

Environments

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

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