Onboarding

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 /gateway/v3/clients/opt-in

Endpoint that generates the link for acceptance terms.

Request Fields

Name	Type	Description	Mandatory
document	Object	Client document	yes
document.type	String	Document type. Allowed values: `CNPJ` or `CPF`	yes
document.number	String	Document number	yes
tradeName	String	Legal name of the client	yes
pixFee	Object	Charged fee data, containing fee type and amount	yes
pixFee.amount	Number	Fixed amount fee for PIX transactions. Mutually exclusive with percentage and min/max values	no
pixFee.percentage	Number	Percentage fee for Pix transactions. Mutually exclusive with fixed amount field	no
pixFee.min	Number	Minimum absolute value for a percentage-based fee. Mutually exclusive with fixed amount field	no
pixFee.max	Number	Maximum absolute value for a percentage-based fee. Mutually exclusive with fixed amount field	no
contact	Object	Client's contact information	yes
contact.name	String	Contact name	yes
contact.email	String	Contact email	yes
contact.phone	String	Contact phone number	yes

Request Example

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

Response Fields

Property	Type	Description
url	String	The URL to the opt-in link for the client
id	String	The unique identifier for the created opt-in link

Response Example

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

GET /gateway/v3/clients/link/:link_id

Endpoint to check the status of terms acceptance.

Request Fields

Property	Type	Description	Mandatory
link_id (path)	String	The unique identifier for the created opt-in link	yes

Response Fields

Property	Type	Description
document	Object	Client document
document.type	String	Document type. Allowed values: `CNPJ` or `CPF`
document.number	String	Document number
status	String	Link status: `CREATED` (generated but not accessed), `INITIATED` (accessed), `FINISHED` (accessed and form submitted)

Response Example

{
  "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:

Header	Description
Authorization	OAuth 2.0 Bearer token. See `POST /token`
apikey	API key provided by Fiserv during the integration
x-timestamp	Request timestamp. Also required in the HMAC signature
x-hmac-signature	HMAC signature. See HMAC Calculation section
x-request-id	Unique random ID to identify the request

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 /gateway/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

Postman Script Example

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/api";
  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.

Request Fields

Property	Type	Description
protocol-id (path)	string	Protocol identifier

Response Fields

Property	Type	Description
protocolId	string	Protocol identification
protocolStatus.status	string	Allowed values: `PROCESSING`, `SUCCESS`, `PARTIAL_SUCCESS`, `ERROR`
protocolStatus.final	boolean	`true` if the protocol is in final state (no more processing expected)
externalProtocolId	string	[Optional] If provided during the original request
payload	object	Original payload
links	object	HATEOAS related links
events[].omniEventId	string	Event UUID
events[].eventType	string	Event type
events[].responseCode	string	Event response code
events[].description	string	Event description
events[].eventStatus	string	Event status: `SUCCESS`, `SKIP`, `ERROR`
events[].eventSource	string	Pix Hub Onboarding component that produced the event

Responses

Code	Description
200	OK
400	Bad Request. See Error format
404	Not Found. See Error format

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 /onboard/api/v4/webhooks

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.

Request Fields

Property	Mandatory	Type / Size	Description
url	yes	String / 255	URL to receive notifications
authType	yes	String	Authentication type. Allowed: `OAuth2`, `HMAC2`, `NONE`
authSettings	no	Object	Authentication Settings
authSettings.authUrl	no	String / 255	Authentication URL. Mandatory if authType is OAUTH2
authSettings.clientId	no	String / 36	Client id. Mandatory if authType is OAUTH2
authSettings.clientSecret	no	String / 255	Client Secret. Mandatory if authType is OAUTH2
authSettings.grantType	no	String / 255	Grant type. Mandatory if authType is OAUTH2
authSettings.apiKey	no	String / 255	Api Key. Mandatory if authType is HMAC
authSettings.apiSecret	no	String / 255	Api Secret. Mandatory if authType is HMAC

Responses

Code	Description
204	No Content – successful execution
400	Bad Request. See Error format

Webhook Examples

Example 1: Webhook not authenticated:

{
  "url": "https://example.your-application-url.here/service-to-receive-callback",
  "authType": "NONE"
}

{
  "url": "https://example.your-application-url.here/service-to-receive-callback",
  "authType": "OAUTH2",
  "authSettings": {
    "authUrl": "https://example.com/auth",
    "clientId": "*****",
    "clientSecret": "*****",
    "grantType": "client_credentials"
  }
}

{
  "url": "https://example.your-application-url.here/service-to-receive-callback",
  "authType": "HMAC",
  "authSettings": {
    "apiKey": "*****",
    "apiSecret": "*****"
  }
}

GET /onboard/api/v4/webhooks

Retrieve current webhook settings.

Response Fields

Property	Type	Description
url	String	URL to receive notifications
authType	String	Authentication type
authSettings.clientIdConfigured	Boolean	Client id flag
authSettings.clientSecretConfigured	Boolean	Client secret flag
authSettings.grantType	String	Grant type
authSettings.apiKeyConfigured	Boolean	API key flag
authSettings.apiSecretConfigured	Boolean	API secret flag

Responses

Code	Description
200	OK
404	Not Found. See Error format

DELETE /onboard/api/v4/webhooks

Remove the current webhook configuration.

Responses

Code	Description
204	No Content – successful execution
404	Not Found. See Error format

Webhook v3 (Deprecated)

The v3 webhook endpoints listed below are legacy and no longer recommended for new integrations.

✅ Please migrate to the equivalent PUT /onboard/api/v4/webhooks, GET /onboard/api/v4/webhooks and DELETE /onboard/api/v4/webhooks endpoints documented above.

PUT /onboard/api/v3/webhook (Deprecated)

Request Fields

Property	Mandatory	Type / Size	Description
url	yes	String / 255	URL to receive notifications
auth	no	Object	Optional authentication object
auth.type	yes	String	Authentication type. Allowed: `OAuth2.0-Bearer`
auth.url	yes	String / 255	Authentication URL
auth.clientId	yes	String	Client ID used to authenticate
auth.clientSecret	yes	String / 255	Client secret used to authenticate

Responses

Code	Description
204	No Content – successful execution
400	Bad Request. See Error format

GET /onboard/api/v3/webhook (Deprecated)

Retrieve current webhook settings.

Response Fields

Property	Type	Description
url	String	URL to receive notifications

Responses

Code	Description
200	OK
404	Not Found. See Error format

DELETE /onboard/api/v3/webhook (Deprecated)

Remove the current webhook configuration.

Responses

Code	Description
204	No Content – successful execution
404	Not Found. See Error format

Webhook Callbacks

Callback Fields v4

Property	Type	Description
protocolId	String	Protocol unique identifier
externalProtocolId	String	External protocol ID (provided on original request)
protocolStatus	String	Protocol status: `PARTIAL_SUCCESS`, `ERROR`, `SUCCESS`, `PROCESSING`
eventStatus	String	Event status: `SUCCESS`, `SKIP`, `ERROR`
eventSource	String	Source of the event
eventType	String	Event type (e.g., `PROTOCOL_COMPLETION`)
responseCode	String	Response code – details the event result
description	String	Description of the event

Callback Examples v4

Example 1: Event completed, async processing not finished:

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

Example 2: Event completed, protocol status is SUCCESS:

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

~~Callback Fields v3 (Deprecated)~~

Property	Type	Description
protocolId	String	Protocol unique identifier
externalProtocolId	String	External protocol ID (provided on original request)
omniClientId	String	Omnihub client id
status	String	Event status: `DONE`, `PROCESSING`, `ERROR`
errors[]	String	Error List
errors[].code	String	Error code
errors[].message	String	Error message

~~Callback Examples v3 (Deprecated)~~

Example 1: Protocol finished with errors

{
  "protocolId": "3077129c-2ef9-4e5e-a38d-557dd56a6948",
  "externalProtocolId": "291aaa16-bde3-4a3d-a875-85b26a670f64",
  "omniClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "DONE",
  "errors": [
    {
      "code": "SITEF_REGISTER_02500",
      "message": "An unexpected error occurred on WS API"
    }
  ]
}

Example 2: Protocol finished successfully

{
  "protocolId": "3077129c-2ef9-4e5e-a38d-557dd56a6948",
  "externalProtocolId": "291aaa16-bde3-4a3d-a875-85b26a670f64",
  "omniClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "DONE",
  "errors": []
}

Pix Gateway

Key Concepts

Account Holder: Represents the CNPJ to which Stores and the registered Pix keys belong to.
Store: Multiple per CNPJ; can be associated only with 1 Account Holder. Needs bound credentials 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. A credential belongs to an Account Holder and can be bound to a Store for transactional use.

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.

Relative resources

During requests, some API fields that reference business entities can be filled by two "kinds" of data:

Serialized json data for an object, such as

{
  ...
  "accountHolder": {
    "legalName": "name",
    "document": {
      "type": "CNPJ",
      "number": "12345678000195"
    } 
  }
  ...
}

In a request, these represent the complete data for an entity's creation (an accountHolder in this case).

Relative path data for a preexisting entity, such as:

{
  ...
  "accountHolder": {
    "rel": "/v4/pix-gateway/account-holders/151251251251"
  }
  ...
}

Values for the rel of an entity are given by the _links_ HATEOAS property

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

Search

POST /v4/pix-gateway/account-holders:search

Search Account Holder by document number, with pagination support.

Request Fields

Property	Type	Description	Mandatory
$pageoffset (query)	Number	Page offset for pagination (starts at 1). Default: `1`	no
$pagelimit (query)	Number	Number of items per page. Default: `10`	no
document	Object	Account Holder document to search by	yes
document.type	String	Document type (`CNPJ` / `CPF`)	yes
document.number	String	Document number	yes

Request Example

{
  "document": {
    "type": "CNPJ",
    "number": "60.664.745/0001-87"
  }
}

Response Fields

Property	Type	Description
accountHolders[].id	String	Account Holder unique identifier
accountHolders[].legalName	String	Account Holder legal name
accountHolders[].links.self.href	String	HATEOAS link to this Account Holder
accountHolders[].links.self.type	String	HTTP method (GET)
totalElements	Number	Total number of elements returned in the search
links.self.href	String	HATEOAS link to repeat this search
links.self.type	String	HTTP method (POST)

Response Example

{
  "accountHolders": [
    {
      "id": "60664745000187",
      "legalName": "Fiserv Inc",
      "links": {
        "self": {
          "href": "/v4/pix-gateway/account-holders/60664745000187",
          "type": "GET"
        }
      }
    }
  ],
  "totalElements": 1,
  "links": {
    "self": {
      "href": "/v4/pix-gateway/account-holders:search?$pageoffset=1&$pagelimit=10",
      "type": "POST"
    }
  }
}

Responses

Code	Description
200	OK

POST /v4/pix-gateway/stores:search

Search Store by document, Account Holder, or external reference ID, optionally filtered by ISV partner. At least one of document, accountHolder or externalReferenceId must be informed.

Request Fields

Property	Type	Description	Mandatory
$pageoffset (query)	Number	Offset for pagination, starting from `0`. Default: `0`	no
$pagelimit (query)	Number	Limit of items per page. Default: `10`	no
document	Object	The resource's store document	no*
document.type	String	Document type (`CNPJ` / `CPF`)	no*
document.number	String	Document number	no*
accountHolder	Object	Relative resource for the Account Holder	no*
accountHolder.rel	String	HATEOAS relative Account Holder URL	no*
externalReferenceId	String	Search by reference used to identify the store externally	no*

* At least one of document, accountHolder, or externalReferenceId is required.

Request Example (search by document)

{
  "document": {
    "type": "CNPJ",
    "number": "60.664.745/0001-87"
  }
}

Request Example (search by document and Account Holder relative resource)

{
  "document": {
    "type": "CNPJ",
    "number": "60.664.745/0001-87"
  },
  "accountHolder": {
    "rel": "/v4/pix-gateway/account-holders/151251251251"
  }
}

Request Example (search by external reference ID)

{
  "externalReferenceId": "NYX-1234567890-ABCDEF"
}

Response Fields

Property	Type	Description
searchStoresPixGatewayResponse[].id	String	Store unique identifier
searchStoresPixGatewayResponse[].legalName	String	Store legal name
searchStoresPixGatewayResponse[].status	String	Store status: `A` (Active) or `I` (Inactive)
searchStoresPixGatewayResponse[].document	String	Store document number
searchStoresPixGatewayResponse[].externalReferenceId	String	Reference used to identify the store externally
searchStoresPixGatewayResponse[].address.country	String	Address country code (ISO 3166-1 alpha-2)
searchStoresPixGatewayResponse[].address.city	String	Address city
searchStoresPixGatewayResponse[].address.province	String	Address state abbreviation (ISO 3166-2)
searchStoresPixGatewayResponse[].address.locality	String	Address district
searchStoresPixGatewayResponse[].address.street	String	Address street
searchStoresPixGatewayResponse[].address.number	String	Address building number
searchStoresPixGatewayResponse[].address.subNumber	String	Address complement
searchStoresPixGatewayResponse[].address.postalCode	String	Address postal code
searchStoresPixGatewayResponse[].links.self.href	String	HATEOAS link to this store
searchStoresPixGatewayResponse[].links.self.type	String	HTTP method (GET)
totalElements	Number	Total number of elements returned in the search
links.self.href	String	HATEOAS link to repeat this search
links.self.type	String	HTTP method (GET)

Response Example

{
  "searchStoresPixGatewayResponse": [
    {
      "id": "845294990001RC",
      "legalName": "Fiserv Inc",
      "status": "A",
      "document": "60664745000187",
      "externalReferenceId": "NYX-1234567890-ABCDEF",
      "address": {
        "country": "BR",
        "city": "Sao Paulo",
        "province": "SP",
        "locality": "Barra Funda",
        "street": "Av Francisco Matarazzo",
        "number": "1000",
        "subNumber": "Suite 101",
        "postalCode": "01140000"
      },
      "links": {
        "self": {
          "href": "/v4/pix-gateway/stores/845294990001RC",
          "type": "GET"
        }
      }
    }
  ],
  "totalElements": 1,
  "links": {
    "self": {
      "href": "/v4/pix-gateway/stores:search?$pageoffset=0&$pagelimit=10",
      "type": "GET"
    }
  }
}

Responses

Code	Description
200	OK
400	Bad Request. See Error format

Account holders

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

Retrieve the given Account Holder information.

Request Fields

Property	Type	Description
id (path)	String	Account Holder unique identifier

Response Fields

Property	Type	Description
id	String	Account Holder unique identifier
legalName	String	Account Holder legal name
document.number	String	Account Holder document number
created	String	Account Holder creation date (ISO-8601)
links.self.href	String	HATEOAS to this account holder
links.self.type	String	HTTP method (GET)

Response Example

{
  "id": "151251251251",
  "legalName": "Fiserv Inc",
  "document": {
    "number": "60664745000187"
  },
  "created": "2026-01-15T13:45:30Z",
  "links": {
    "self": {
      "href": "/v4/pix-gateway/account-holders/151251251251",
      "type": "GET"
    }
  }
}

Responses

Code	Description
200	OK
400	Bad Request. See Error format
401	Unauthorized. See Error format
403	Forbidden. See Error format
404	Not Found. See Error format

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

Retrieve the given Account Holder's credential information.

Request Fields

Property	Type	Description
id (path)	String	Account Holder unique identifier

Response Fields

Property	Type	Description
_embedded.credentialList[].id	String	Credential unique identifier
_embedded.credentialList[].pspIspb	String	Credential PSP ISPB code
_embedded.credentialList[].pixKey	String	Credential Pix key
_embedded.credentialList[].pixKeyType	String	Credential Pix type
_embedded.credentialList[].transactionalDocument	String	Transactional document. Some ISPBs have this additional information
_embedded.credentialList[].credentialAlias	String	Credential Pix transaction alias
_embedded.credentialList[].name	String	Credential name
_embedded.credentialList[].links.self.href	String	HATEOAS to this account holder credential
_embedded.credentialList[].links.self.type	String	HTTP method (GET)

Response Example

{
  "_embedded": {
    "credentialList": [
      {
        "id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678",
        "pspIspb": "12345678",
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ",
        "transactionalDocument": "60664745000187",
        "credentialAlias": "fiserv-inc-main",
        "name": "Fiserv Inc Main Credential",
        "links": {
          "self": {
            "href": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
            "type": "GET"
          }
        }
      }
    ]
  }
}

Responses

Code	Description
200	OK
400	Bad Request. See Error format
401	Unauthorized. See Error format
403	Forbidden. See Error format
404	Not Found. See Error format

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.

Request Fields

Property	Mandatory	Type / Size	Description
document	yes	Object	Store document data
document.type	yes	String	Store document type (`CPF` / `CNPJ`)
document.number	yes	String / [11, 18]	Store document number
externalReferenceId	no	String	Additional store identifier. Must be unique for stores with the same legal document
address	yes	Object	Store address data
address.country	yes	String / 2	Address country code (ISO 3166-1 alpha-2). Recommended values are `BR`, `AR` and `UY`. Other values may not be supported
address.locality	yes	String / 30	Store district
address.city	yes	String / 15	Store city
address.number	yes	String / 9	Store address number
address.postalCode	yes	String / [8, 9]	Store postal code
address.province	yes	String / 2	Store state abbreviation (ISO 3166-2)
address.street	yes	String / 110	Store street
address.subNumber	no	String / 30	Store address complement
tradeName	yes	String / 25	Store trade name
transactionCallback	no	Object	Callback data for transaction purposes
transactionCallback.url	yes	String / 255	Callback URL for payment transaction purposes
transactionCallback.apiKey	yes	String / [24, 50]	API key used to sign the callback request
transactionCallback.apiSecret	yes	String / [32, 64]	API secret used to sign the callback request
accountHolder	yes	Object	Store's Account Holder data
accountHolder.rel*	no	String / 255	HATEOAS relative Account Holder URL. If provided, uses this resource; if not, creates a new account holder
accountHolder.document.type**	no	String	Account Holder document type (`CPF` / `CNPJ`)
accountHolder.document.number**	no	String / [11, 18]	Account Holder document number
accountHolder.legalName**	no	String / 100	Account holder legal name
router	no	Object	n
router.routerType	yes	String	Routing type: `BALANCING` or `CONTINGENCY`
router.routes[].balancingWeight	no	Number	Route's balancing weight (used in `BALANCING` routing)
router.routes[].pspIspb	yes	String / 8	Route's PSP ISPB code
router.routes[].routeOrder	no	Number	Route order for `CONTINGENCY` routing (1 = first route)
automaticPix	no	Array	Automatic Pix configuration list
automaticPix[]	no	Object	Automatic Pix configuration item
automaticPix[].pspIspb	yes	String / 8	Automatic Pix - PSP ISPB code
automaticPix[].agency	yes	String	Automatic Pix – agency number
automaticPix[].account	yes	String	Automatic Pix – account number
automaticPix[].accountType	yes	String	Automatic Pix – account type
credentials	no	Array	List containing credential data
credentials[]	no	Object	Object containing a specific Pix credential's data
credentials[].rel*	no	String / 255	Relative resource for credential
credentials[].pspIspb**	no	String / 8	Credential's PSP ISPB code
credentials[].pixClientId**	no	String	Credential's Pix Client ID
credentials[].pixClientSecret**	no	String	Credential's Pix Client secret
credentials[].pixKey**	no	String	Credential's Pix key
credentials[].transactionalDocument	no	String	Transactional document. Some PSPs require this additional information
credentials[].default	no	Boolean	Whether this credential should be used as default for transactions
credentials[].dynamicFields	no	Object	Dynamic fields. Key value format
credentials[].name	no	String	Credential's name
credentials[].pixKeyStoreAssociation	no	Object	Specific Pix key configurations for this store's use of the credential
credentials[].pixKeyStoreAssociation.pixKey	yes	String	Specific Pix key for use by the store
credentials[].pixKeyStoreAssociation.pixKeyType	yes	String	Pix key type: `CNPJ`, `CPF`, `CELULAR`, `EMAIL`, or `ALEATORIO`

Note: Use either the fields marked with * or **.

Request Example (inline Account Holder and Credential data)

{
  "document": {
    "type": "CNPJ",
    "number": "60664745000187"
  },
  "externalReferenceId": "store-001",
  "address": {
    "country": "BR",
    "locality": "Barra Funda",
    "city": "Sao Paulo",
    "number": "1000",
    "postalCode": "01140000",
    "province": "SP",
    "street": "Av Francisco Matarazzo",
    "subNumber": "Suite 101"
  },
  "tradeName": "Fiserv Inc",
  "transactionCallback": {
    "url": "https://example.your-application-url.here/pix-callback",
    "apiKey": "a1b2c3d4e5f6a1b2c3d4e5f6",
    "apiSecret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
  },
  "accountHolder": {
    "document": {
      "type": "CNPJ",
      "number": "60664745000187"
    },
    "legalName": "Fiserv Inc"
  },
  "router": {
    "routerType": "BALANCING",
    "routes": [
      {
        "pspIspb": "12345678",
        "balancingWeight": 100
      }
    ]
  },
  "automaticPix": [
    {
      "pspIspb": "12345678",
      "agency": "0001",
      "account": "123456",
      "accountType": "CORRENTE"
    }
  ],
  "credentials": [
    {
      "pspIspb": "12345678",
      "pixClientId": "client-id-example",
      "pixClientSecret": "client-secret-example",
      "pixKey": "60664745000187",
      "transactionalDocument": "60664745000187",
      "default": true,
      "name": "Fiserv Inc Main Credential",
      "pixKeyStoreAssociation": {
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ"
      }
    }
  ]
}

Request Example (relative resources for Account Holder and Credential)

{
  "document": {
    "type": "CNPJ",
    "number": "60664745000187"
  },
  "externalReferenceId": "store-002",
  "address": {
    "country": "BR",
    "locality": "Barra Funda",
    "city": "Sao Paulo",
    "number": "1000",
    "postalCode": "01140000",
    "province": "SP",
    "street": "Av Francisco Matarazzo",
    "subNumber": "Suite 101"
  },
  "tradeName": "Fiserv Inc",
  "transactionCallback": {
    "url": "https://example.your-application-url.here/pix-callback",
    "apiKey": "a1b2c3d4e5f6a1b2c3d4e5f6",
    "apiSecret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
  },
  "accountHolder": {
    "rel": "/v4/pix-gateway/account-holders/151251251251"
  },
  "router": {
    "routerType": "CONTINGENCY",
    "routes": [
      {
        "pspIspb": "12345678",
        "routeOrder": 1
      },
      {
        "pspIspb": "87654321",
        "routeOrder": 2
      }
    ]
  },
  "credentials": [
    {
      "rel": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "pixKeyStoreAssociation": {
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ"
      }
    }
  ]
}

Response Fields

Property	Type	Description
id	String	Store identification
externalReferenceId	String	Additional store identifier
omniPaymentId	String	Identification for omni-payment used in transactions
accountHolder.id	String	Account holder identification
accountHolder.rel	String	HATEOAS relative URL for the Account Holder
credentials[].id	String	Credential's unique identification
credentials[].pspIspb	String	Credential's PSP ISPB code
credentials[].credentialAlias	String	Credential's transaction alias
credentials[].pixKeyStoreAssociation	Object	Specific pix key configurations for this Store’s use of the credential
credentials[].pixKeyStoreAssociation.pixKey	String	Specific pix key for use by the store created
credentials[].pixKeyStoreAssociation.pixKeyType	String	Pix key type; May be `CNPJ`, `CPF`, `CELULAR` (phone number), `EMAIL` or `ALEATORIO` (random UUID)
credentials[].link.self.href	String	Credential's HATEOAS link
credentials[].link.self.type	String	Credential's HATEOAS HTTP method
protocol.href	String	HATEOAS link for retrieving protocol information
protocol.type	String	HTTP method for protocol link (`GET`)

Response Example

{
  "id": "store-id-123456",
  "externalReferenceId": "store-001",
  "omniPaymentId": "omnipay-98765",
  "accountHolder": {
    "id": "151251251251",
    "rel": "/v4/pix-gateway/account-holders/151251251251"
  },
  "credentials": [
    {
      "id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "pspIspb": "12345678",
      "credentialAlias": "fiserv-inc-main",
      "pixKeyStoreAssociation": {
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ"
      },
      "link": {
        "self": {
          "href": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
          "type": "GET"
        }
      }
    }
  ],
  "protocol": {
    "href": "/v4/protocol/faae306f-4018-3d2a-941c-79df4414c5ea",
    "type": "GET"
  }
}

Responses

Code	Description
201	Created (synchronous)
202	Accepted (asynchronous)
400	Bad Request. See Error format
401	Unauthorized. See Error format
403	Forbidden. See Error format
404	Not Found. See Error format
409	Conflict. See Error format

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

Retrieve the given Store data.

Request Fields

Property	Type	Description
id (path)	String	Store unique identifier

Response Fields

Property	Type	Description
document.type	String	Store document type (`CPF` / `CNPJ`)
document.number	String	Store document number
omniPaymentId	String	[Legacy] The first OmniPayment identifier for this store
omniPaymentIds[]	Array	List of OmniPayment identifiers related to the establishment
externalReferenceId	String	Additional store identifier
address.locality	String	Store district
address.city	String	Store city
address.number	String	Store address number
address.postalCode	String	Store postal code
address.province	String	Store state
address.street	String	Store street
address.subNumber	String	Store address complement
tradeName	String	Store trade name
transactionCallback.url	String	Callback URL for payment transaction purposes
accountHolder.document.type	String	Account Holder document type
accountHolder.document.number	String	Account Holder document number
accountHolder.legalName	String	Account holder legal name
accountHolder.link.self.href	String	Account holder HATEOAS link
accountHolder.link.self.type	String	Account holder HATEOAS HTTP method
router.routerType	String	Routing type: `BALANCING` or `CONTINGENCY`
router.routes[].balancingWeight	Number	Route's balancing weight
router.routes[].pspIspb	String	Route's PSP ISPB code
router.routes[].routeOrder	Number	Route order (1 = first route)
automaticPix[].pspIspb	String	Automatic Pix - PSP ISPB code
automaticPix[].agency	String	Automatic Pix – agency number
automaticPix[].account	String	Automatic Pix – account number
automaticPix[].accountType	String	Automatic Pix – account type
automaticPix[].agreement	String	Agreement code, required when merchant has more than one agreement associated with the same agency and account
automaticPix[].automaticPixEnabled	String	If automatic pix is enabled, it should return `SIM`, otherwise, it should return `NAO`
credentials[].rel	String	HATEOAS rel link
credentials[].id	String	Credential identification
credentials[].pspIspb	String	Credential's PSP ISPB code
credentials[].pixKey	String	Credential's Pix key
credentials[].credentialAlias	String	Credential alias for payment transaction use
credentials[].dynamicFields	Object	Key value with dynamic fields
credentials[].name	String	Credential’s Name
credentials[].transactionalDocument	String	Transactional document. Some ISPBs have this additional information
credentials[].default	Boolean	Default credential for payment transaction use
credentials[].link.self.href	String	Credential's HATEOAS link
credentials[].link.self.type	String	Credential's HATEOAS HTTP method

Response Example

{
  "document": {
    "type": "CNPJ",
    "number": "60664745000187"
  },
  "omniPaymentId": "omnipay-98765",
  "omniPaymentIds": ["omnipay-98765"],
  "externalReferenceId": "store-001",
  "address": {
    "locality": "Barra Funda",
    "city": "Sao Paulo",
    "number": "1000",
    "postalCode": "01140000",
    "province": "SP",
    "street": "Av Francisco Matarazzo",
    "subNumber": "Suite 101"
  },
  "tradeName": "Fiserv Inc",
  "transactionCallback": {
    "url": "https://example.your-application-url.here/pix-callback"
  },
  "accountHolder": {
    "document": {
      "type": "CNPJ",
      "number": "60664745000187"
    },
    "legalName": "Fiserv Inc",
    "link": {
      "self": {
        "href": "/v4/pix-gateway/account-holders/151251251251",
        "type": "GET"
      }
    }
  },
  "router": {
    "routerType": "BALANCING",
    "routes": [
      {
        "pspIspb": "12345678",
        "balancingWeight": 100
      }
    ]
  },
  "automaticPix": [
    {
      "pspIspb": "12345678",
      "agency": "0001",
      "account": "123456",
      "accountType": "CORRENTE",
      "agreement": "001",
      "automaticPixEnabled": "SIM"
    }
  ],
  "credentials": [
    {
      "rel": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "pspIspb": "12345678",
      "pixKey": "60664745000187",
      "credentialAlias": "fiserv-inc-main",
      "dynamicFields": {},
      "name": "Fiserv Inc Main Credential",
      "transactionalDocument": "60664745000187",
      "default": true,
      "link": {
        "self": {
          "href": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
          "type": "GET"
        }
      }
    }
  ]
}

Responses

Code	Description
200	OK
400	Bad Request. See Error format
401	Unauthorized. See Error format
403	Forbidden. See Error format
404	Not Found. See Error format

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.

Request Fields

Property	Mandatory	Type / Size	Description
id (path)	yes	String	Store unique identification
transactionCallback	no	Object	Callback data for transaction purposes
transactionCallback.url	yes	String / 255	Callback URL for payment transaction purposes
transactionCallback.apiKey	yes	String / [24, 50]	API key used to sign the callback request
transactionCallback.apiSecret	yes	String / [32, 64]	API secret used to sign the callback request
router	no	Object	Transaction routing configuration
router.routerType	yes	String	Routing type: `BALANCING` or `CONTINGENCY`
router.routes[].balancingWeight	no	Number	Route's balancing weight
router.routes[].pspIspb	yes	String / 8	Route's PSP ISPB code
router.routes[].routeOrder	no	Number	Route order for `CONTINGENCY` routing
automaticPix	no	Array	Automatic Pix configuration list
automaticPix[]	no	Object	Automatic Pix configuration item
automaticPix[].pspIspb	yes	String / 8	Automatic Pix - PSP ISPB code
automaticPix[].agency	yes	String	Automatic Pix – agency number
automaticPix[].account	yes	String	Automatic Pix – account number
automaticPix[].accountType	yes	String	Automatic Pix – account type
credentials	no	Array	List containing credential data
credentials[]	no	Object	Object containing a specific Pix credential's data
credentials[].rel*	no	String / 255	Relative resource for credential
credentials[].pspIspb**	no	String / 8	Credential's PSP ISPB code
credentials[].pixClientId**	no	String	Credential's Pix Client ID
credentials[].pixClientSecret**	no	String	Credential's Pix Client secret
credentials[].pixKey**	no	String	Credential's Pix key
credentials[].transactionalDocument**	no	String	Transactional document. Some ISPBs have this additional information
credentials[].dynamicFields**	no	String	Dynamic fields
credentials[].name**	no	String	Credential’s Name
credentials[].pixKeyStoreAssociation	no	Object	Specific Pix key configurations for this store's use of the credential
credentials[].pixKeyStoreAssociation.pixKey	yes	String	Specific Pix key for use by the store
credentials[].pixKeyStoreAssociation.pixKeyType	yes	String	Pix key type: `CNPJ`, `CPF`, `CELULAR`, `EMAIL`, or `ALEATORIO`
credentials[].default	no	Boolean	Whether this credential should be used as default for transactions

Note: Use either the fields marked with * or **.

Request Example (inline Credential data)

{
  "transactionCallback": {
    "url": "https://example.your-application-url.here/pix-callback",
    "apiKey": "a1b2c3d4e5f6a1b2c3d4e5f6",
    "apiSecret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"
  },
  "router": {
    "routerType": "BALANCING",
    "routes": [
      {
        "pspIspb": "12345678",
        "balancingWeight": 100
      }
    ]
  },
  "automaticPix": [
    {
      "pspIspb": "12345678",
      "agency": "0001",
      "account": "123456",
      "accountType": "CORRENTE"
    }
  ],
  "credentials": [
    {
      "pspIspb": "87654321",
      "pixClientId": "client-id-example-2",
      "pixClientSecret": "client-secret-example-2",
      "pixKey": "60664745000187",
      "transactionalDocument": "60664745000187",
      "dynamicFields": {},
      "name": "Fiserv Inc Secondary Credential",
      "default": false,
      "pixKeyStoreAssociation": {
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ"
      }
    }
  ]
}

Request Example (relative resource for Credential)

{
  "router": {
    "routerType": "CONTINGENCY",
    "routes": [
      {
        "pspIspb": "12345678",
        "routeOrder": 1
      },
      {
        "pspIspb": "87654321",
        "routeOrder": 2
      }
    ]
  },
  "credentials": [
    {
      "rel": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "default": true,
      "pixKeyStoreAssociation": {
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ"
      }
    }
  ]
}

Response Fields

Property	Type	Description
id	String	Store identification
externalReferenceId	String	Additional store identifier
omniPaymentId	String	The identification for omni-payment used in transactions
credentials[].id	String	Credential's unique identification
credentials[].pspIspb	String	Credential's PSP ISPB code
credentials[].credentialAlias	String	Credential's transaction alias
credentials[].pixKeyStoreAssociation	Object	Specific pix key configurations for this Store’s use of the credential
credentials[].pixKeyStoreAssociation.pixKey	String	Specific pix key for use by the store
credentials[].pixKeyStoreAssociation.pixKeyType	String	Pix key type. May be `CNPJ`, `CPF`, `CELULAR` (phone number), `EMAIL` or `ALEATORIO` (random UUID)
credentials[].link.self.href	String	Credential's HATEOAS link
credentials[].link.self.type	String	Credential's HATEOAS HTTP method
protocol.href	String	Link for retrieving protocol information
protocol.type	String	HTTP method for href (`GET`)

Response Example

{
  "id": "store-id-123456",
  "externalReferenceId": "store-001",
  "omniPaymentId": "omnipay-98765",
  "credentials": [
    {
      "id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "pspIspb": "87654321",
      "credentialAlias": "fiserv-inc-secondary",
      "pixKeyStoreAssociation": {
        "pixKey": "60664745000187",
        "pixKeyType": "CNPJ"
      },
      "link": {
        "self": {
          "href": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
          "type": "GET"
        }
      }
    }
  ],
  "protocol": {
    "href": "/v4/protocol/faae306f-4018-3d2a-941c-79df4414c5ea",
    "type": "GET"
  }
}

Responses

Code	Description
200	OK (synchronous)
202	Accepted (asynchronous)
400	Bad Request. See Error format
401	Unauthorized. See Error format
403	Forbidden. See Error format
404	Not Found. See Error format

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

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

Request Fields

Property	Type	Description
store-id (path)	String	Store unique identifier
credential-id (path)	String	Credential unique identifier

Responses

Code	Description
204	No Content

Credentials

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

Retrieve the given Credential data.

Request Fields

Property	Type	Description
id (path)	String	Credential unique identifier

Response Fields

Property	Type	Description
id	String	Credential unique identifier
pspIspb	String	Credential's PSP ISPB code
name	String	Credential's name
credentialAlias	String	Credential alias used for transactional purposes
links.self.href	String	Credential's HATEOAS link
links.self.type	String	Credential's HATEOAS HTTP method

Response Example

{
  "id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678",
  "pspIspb": "12345678",
  "name": "Fiserv Inc Main Credential",
  "credentialAlias": "fiserv-inc-main",
  "links": {
    "self": {
      "href": "/v4/pix-gateway/credentials/a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "type": "GET"
    }
  }
}

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

Delete the given Credential. A Credential bound to any store must be unbound before it is deleted.

For credential unbinding, check the DELETE /v4/pix-gateway/stores/{store-id}/credentials/{credential-id} endpoint in the Store section

Request Fields

Property	Type	Description
id (path)	String	Credential unique identifier

Responses

Code	Description
204	No Content – successful execution

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.

Request Fields

Property	Type	Description
status (query)	String	PSP status filter: `I` – Integrated, `C` – Inactive, `N` – Not integrated

Response Fields

Property	Type	Description
psps[].id	String	PSP ISPB code
psps[].name	String	PSP name
psps[].status	String	PSP status
links.self.href	String	PSP HATEOAS link
links.self.type	String	PSP HATEOAS HTTP method

Response Example

{
  "psps": [
    {
      "id": "12345678",
      "name": "PSP Example Bank",
      "status": "I"
    },
    {
      "id": "87654321",
      "name": "PSP Another Bank",
      "status": "I"
    }
  ],
  "links": {
    "self": {
      "href": "/v4/pix-gateway/psps",
      "type": "GET"
    }
  }
}

Responses

Code	Description
200	OK

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

Retrieve the given PSP information.

Request Fields

Property	Type	Description
id (path)	String	PSP ISPB code
transactionalDocument (query)	String	Transactional document. If not sent, might fail for some PSPs

Response Fields

Property	Type	Description
id	String	PSP ISPB code
name	String	PSP name
status	String	PSP status
credentialFields[].field	String	Field identification to use on `credentials[].dynamicField`
credentialFields[].label	String	Field label with a short description
credentialFields[].size	String	Field value size limit
credentialFields[].description	String	Field description with detailed information
links.self.href	String	PSP HATEOAS link
links.self.type	String	PSP HATEOAS HTTP method

Response Example

{
  "id": "12345678",
  "name": "PSP Example Bank",
  "status": "I",
  "credentialFields": [
    {
      "field": "pixClientId",
      "label": "Client ID",
      "size": "36",
      "description": "Client identifier provided by the PSP for Pix transactions"
    },
    {
      "field": "pixClientSecret",
      "label": "Client Secret",
      "size": "64",
      "description": "Client secret provided by the PSP for Pix transactions"
    }
  ],
  "links": {
    "self": {
      "href": "/v4/pix-gateway/psps/12345678",
      "type": "GET"
    }
  }
}

Responses

Code	Description
200	OK

Updated 6 days ago

Did this page help you?