Create or replace credentials

The Pismo platform enables you to securely create or replace an external provider's API key (or other credentials), using the Execute create or replace credential endpoint.

For example, Pix is an instant payment system that enables the transfer of digital payments and funds in Brazil. It's administered by the Central Bank of Brazil (BCB). An organization can participate in the Pix network in one of two ways:

• Direct integration – An organization is directly integrated with BCB.
• Indirect integration – A Brazilian organization that is not directly integrated with BCB can make Pix transfers using the services provided by a Pismo partner who is a direct participant in the BCB's Instant Payment System (SPI).

It's in the case of indirect integration that the Execute create or replace credential endpoint is needed. Assume that organization A is not directly integrated with BCB. Assume that organization B is a direct participant in SPI and is partnered with Pismo. Organization B can provide instant payment settlement services to organization A. The flow is as follows:

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 Execute create or replace credential endpoint to send the API key to Pismo. The endpoint creates a proxy value for the API key. 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.
5. By going through Pismo, organization A is able to use organization B's API key to make Pix transfers.

📘

Organization A is not limited to using the API key for Pix transfers. It can also use it for webhook configuration and Pix key management.

Sample request

The following code demonstrates how you can pass the data needed to create or replace a client ID in the body of the v1/credentials endpoint.

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

📘

The provider_data field might have specific requirements mandated by the provider.

When you call the enpoint, the api performs a test to try 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"
}