Create or replace credentials

You have the option to securely create or replace an external provider's API key (or other credentials).

For example, Pix is an instant payment system, administered by the Central Bank of Brazil (BCB), that enables the transfer of digital payments and funds in Brazil. .

An organization can participate in the Pix network in one of two ways:

  • Direct participant – An organization that is directly integrated with the BCB.
  • Indirect participant – An organization that can make Pix transfers via a direct participant.

An indirect participant needs to call the Create provider credential endpoint. Assume the following:

  • Organization A is not directly integrated with the BCB.
  • Organization B is a direct participant and is partnered with Pismo.

Organization B can provide instant payment settlement services to Organization A via the following steps:

  1. Organization A establishes a settlement account with Organization B.
  2. Organization A informs Pismo that it wants to use Organization B's instant payment settlement services.
  3. Organization A generates an API Key in Organization B's admin environment.
  4. Organization A uses the Create provider credential endpoint to send the API key to Pismo, which creates a proxy value for the API key.
  5. Pismo sends this proxy value to organization A. No one in Organization B or Pismo is able to see the real value of the API key.

By going through Pismo, Organization A is able to use organization B's API key to make Pix transfers.

Sample request

The following code shows the data needed to create or replace a client ID in the endpoint body.

     "key": "71069360002100",
     "provider": " [organization B]",
     "type": "PIX",       
     "provider_data": {
          "client_id": "Jk10014812-4785-1293-cded-3683ce1fdwjdj"

The following table explains the fields in the sample code:

keyYExternal provider authentication key
providerYService provider
typeYUse PIX for integration with the Brazilian indirect instant payment system. Use PAY2ALL for account creation and closing and for Pay2all's generic cashout.
provider_dataDepends on organizationProvider data metadata. The provider might have specific requirements for this field.

When you call the endpoint, a test is performed to authenticate the provider:

  • If successful, the credentials are inserted in the database or updated if they already exist.
  • If the test fails, an error is returned.

If the request succeeds, the body of the response looks like this:

	"message": "Credential saved"

If the request fails, an error code and message are returned. For example:

	"message": "[organization B] - API Invalid credential",
	"code": "EBAA0018"