Este documento describe las API, REST y los recursos proporcionados por Fiserv. Nuestros sistemas son fiables con un gran rendimiento y elasticidad. Como líder empresarial en el segmento de pagos, las API brindarán una oportunidad a los desarrolladores para aprovechar nuestro ecosistema de pagos y nuestra amplia infraestructura.

Nuestras APIs tienen rutas URI y utilizan autenticación HTTP nativa, lo que proporciona un acceso seguro a la información. Realice solicitudes HTTP utilizando los métodos GET y POST, reciba respuestas en formato JSON. Esto permite que los desarrolladores utilicen cualquier lenguaje de programación para acceder a nuestras API, integrarse de manera segura y crear varias aplicaciones diferentes.

Para comenzar a utilizar nuestras API, el desarrollador deberá seguir los pasos que se indican a continuación:

1. Crear un usuario o contraseña en el portal de desarrollo;
2. Cuando esté listo el entendimiento de las APIs y el desarrollo de la integración esté en curso, solicite el Token de Usuario/Contraseña a través de la casilla [email protected] enviar el correo electrónico, por favor, proporcione:
   • Asunto: Solicitud de autenticación del usuario;
   • Cuerpo:
   1. Su nombre / Nombre de la empresa
   2. Descripción de la empresa: Breve descripción de su empresa;
   3. Representante de Fiserv: ¿Quién del equipo comercial de Fiserv trabaja con su empresa?
   4. Institución *: Con qué Institución se relaciona la integración, por ejemplo: BIN, Sicredi, etc.;
   5. Contrato de Servicio *: Contrato de Servicio registrado en Fiserv;
   6. E-mail: Correo electrónico de contacto institucional;
   7. Número de teléfono: Número de teléfono institucional de contacto;
   8. Comentarios: Cualquier comentario que desee agregar, relacionado con el proyecto de integración;
3. Utilice los valores de Usuario/Contraseña para generar un token de autenticación. El token se utilizará para acceder a las API
4. Cree una aplicación en el menú Aplicación y seleccione los productos a los que desea tener acceso
5. Utilice los valores disponibles para "Clave de consumidor" y "Secreto de consumidor" en la página de la aplicación (se les pedirá que accedan a las API)

*Si no está al tanto de su Institución o Contrato de Servicio, comuníquese con su representante de Fiserv.

Generación de tokens

Aviso importante:

1. La custodia de las credenciales es responsabilidad del cliente;
2. No compartir las Credenciales con quien no deba tener acceso a las mismas;
3. Almacene las credenciales de token en una bóveda específica. Evite almacenar en la misma base de datos de aplicaciones que consumirá recursos;
4. En caso de compromiso/pérdida de sus credenciales, debe ponerse en contacto con nosotros de inmediato;

Solicitud

Para recibir el token, debe enviar una solicitud POST para “Token Access” con los siguientes parámetros:

De donde:

1. user_name: el nombre de usuario que obtuviste en los Primeros Pasos.
2. Contraseña: La contraseña que obtuviste en los Primeros Pasos.

Respuesta

La respuesta POST es un JSON con la siguiente información:

Donde access_token es el valor que se usará en todas las demás API.
Ejemplo de respuesta

{  
  "access_token": "eyJhbGciOiJS [...] swVHg6f8opW1DzuWsilvQ",  
  "expires_in": 62208000,  
  "refresh_expires_in": 1800,  
  "refresh_token": "eyJhbGciOiJS [...] G8LSL7qfJLmLU59O8sskw",  
  "token_type": "bearer",  
  "id_token": "eyJhbGciOiJS [...] 3utG5l7qC0ieC--oLzGQ6w",  
  "not-before-policy": 0,  
  "session_state": "3a639a9b-2c42-472e-911b-209f9e01e077"  
}

Autenticación

Las API de Fiserv utilizan la autenticación HMAC.

Para poder acceder a cualquiera de los Códigos o APIs descritos en esta plataforma, requerirá las credenciales enviadas por correo electrónico. ¿No tienes las credenciales? Crea tu cuenta y solicita un Usuario/Contraseña enviando un e-mail a la casilla [email protected].

Deberá enviar los siguientes parámetros en el encabezado para cada solicitud de API:

Auth

En el parámetro auth - encabezado - el usuario debe enviar el valor obtenido en los detalles del token.
Ejemplo de Token: "eyJhbGciOiJSUzI1NiIsInR5cCIgO [...] tFlCzaiEx06ETdkwoTC-CfzSaVA"

Api-Key

Clave obtenida de la página de la aplicación para desarrolladores
Ejemplo: "X0GW3QGOYFn4r7DHcVC8KuatUnNs6MGB"

Timestamp

Fecha actual en formato "Unix epoch time" en milisegundos, que consiste en un número en milisegundos desde las 00:00 hasta el 1 de enero de 1970.
Ejemplo: 1568914752721

Message-Signature

Autenticación de cadena HMAC.
Para generar esta cadena, el usuario debe seguir los pasos a continuación:

1. Obtener la clave de la aplicación para desarrolladores: appKey
2. Obtener la contraseña de la aplicación para desarrolladores: secreto
3. Genere la fecha en formato de época Unix - milisegundos (Fecha)
4. Generar una cadena alfanumérica aleatoria (Client-Request-Id)
5. Crear el JSON que se enviará en cuerpo (solicitud POST)
6. Concatene todos los elementos de instrucciones 1, 3, 4 y 5: appKey + Cliente + Fecha + JSON
7. Cifre el resultado del elemento #6 (OpenSSL base64 usando el secreto - elemento #2 - como clave HMAC)
8. Proporcione la cadena #7 como parámetro "Message-Signature"

Client-Request-Id

Cadena alfanumérica generada por el usuario.
Ejemplo: "6NYHj9Pgyxc84rmafpwG4fjhLwFfJYFVmxJOcgziD0QN3q6mGC"

Códigos de estado para API REST

Fiserv devuelve el estado del código estándar HTTP, para solicitudes exitosas y no exitosas. Consulte la siguiente tabla para obtener más detalles:

GET

Ejemplo en Postman

A continuación se muestra un ejemplo de una solicitud GET de verificación CEP, mediante Postman.

Los parámetros en el encabezado son:

La respuesta es:

Ejemplo en Python 3

Código

    from hashlib import sha256  
    import base64  
    import time  
    import hmac  
    import requests  
    import random  
    import string  
    import json
    
# appkey extraída da página da aplicação do desenvolvedor
appkey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# senha extraída da página da aplicação do desenvolvedor
secret = "XXXXXXXXXXXXXXXX"

# url das APIs
url = "https://int.api.firstdata.com"

# endpoint da API
endpoint = "/sba/cep-service/cep/04794000"

# token obtido através da API de Token
token = 'eyJhbGciOiJSUzI1NiIsIn[...]dPdcIGGIEz76SP6GoHcdYTJQnmBYg'

# data no formato "Unix epoch time" em milissegundos
dt = str(int(time.time() * 1000))

# string alfanumérica gerada pelo usuário
client_request_id = ''.join(random.choice(string.ascii_uppercase +
                                          string.ascii_lowercase +
                                          string.digits) for _ in range(50))

# concatenação de strings
string_to_sign = appkey + client_request_id + dt

# encriptação da string usando hmac com sha256
encoded_signature = base64.b64encode(hmac.new(secret.encode(),
                                     string_to_sign.encode(),
                                     sha256).digest()).decode()

# string que será enviada como parâmetro "Message-Signature" no header
hmac_auth = 'encoded_signature'

# dicionário "headers" com todos os parâmetros que serão enviados no request
headers = {
    'auth': token,
    'Api-Key': appkey,
    'Timestamp': dt,
    'Message-Signature': hmac_auth,
    'Client-Request-Id': client_request_id,
}

# envio do request e impressão do resultado (status e body)
r = requests.get(url + endpoint, headers=headers)
print(f'Status: {r.status_code}\n'
      f'Body: {json.dumps(r.json(), indent=4, sort_keys=True, ensure_ascii=False)}')

Output

    Status: 200  
    Body: {  
        "cepResponse": {  
            "address": "Avenida das Nações Unidas",  
            "city": "São Paulo",  
            "complement": "- lado ímpar",  
            "genericZipCode": "Não",  
            "neighborhood": "Vila Gertrudes",  
            "state": "SP",  
            "zipCode": "04794000"  
        },  
        "code": 200,  
        "description": "Search done successfully!"  
    }

Ejemplo en Shell del Script

Código

#!/bin/bash

# appkey extraída da página da aplicação do desenvolvedor
APPKEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # Api Key (ou chave publica) gerada pelo Apigee

# senha extraída da página da aplicação do desenvolvedor
SECRET="XXXXXXXXXXXXXXXX" # Chave secreta gerada pelo APIGEE

# url da API
URL="https://int.api.firstdata.com/sba/cep-service/cep/04794000"

# data no formato "Unix epoch time" em milissegundos
DATE=`Date +%s%3N` #Data em formato epoch

# string alfanumérica gerada pelo usuário
CLIENT_REQUEST_ID=`head /dev/urandom | tr -dc A-Za-z0-9 | head -c 50 ; echo ''`

# token obtido através da API de Token
TOKEN="eyJhbGciOiJSUzI1NiIsIn[...]dPdcIGGIEz76SP6GoHcdYTJQnmBYg"

# concatenação de strings
STRING_TO_SIGN=$APPKEY$CLIENT_REQUEST_ID$DATE

# encriptação da string usando hmac com sha256
ENCODED_SIGNATURE=$(echo -n $STRING_TO_SIGN | openssl sha256 -binary -hmac $SECRET | base64) #Estamos com suporte ao sha256 somente

# string que será enviada como parâmetro "Message-Signature" no header
HMAC_AUTH=$ENCODED_SIGNATURE

# envio do request com parâmetros no header
curl -H "auth: $TOKEN" -H "Api-Key: $APPKEY" -H "Timestamp: $DATE" -H "Message-Signature: $HMAC_AUTH" -H "Client-Request-Id: $CLIENT_REQUEST_ID" $URL

Output

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current  
                                     Dload  Upload   Total   Spent    Left  Speed  
    100   249    0   249    0     0     86      0 --:--:--  0:00:02 --:--:--    86  
    {"code":200,"description":"Search done successfully!","cepResponse":{"state":"SP","city":"São Paulo","neighborhood":"Vila Gertrudes","address":"Avenida das Nações Unidas","complement":"- lado ímpar","zipCode":"04794000","genericZipCode":"Não"}}

Post

Ejemplo en Postman

Seguimiento de la solicitud POST de actualización de la dirección en Postman.

Los parámetros en el encabezado son:

El código JSON es:

La respuesta es:

Ejemplo en Python 3

Código

    from hashlib import sha256  
    import base64  
    import time  
    import hmac  
    import requests  
    import random  
    import string  
    import json

# appkey extraída da página da aplicação do desenvolvedor
appkey = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# senha extraída da página da aplicação do desenvolvedor
secret = "XXXXXXXXXXXXXXXX"

# url das APIs
url = "https://int.api.firstdata.com"

# endpoint da API
endpoint = "/wsm/merchantinfo/accounts"

# body que será enviado (requests POST)
body = {
    "paymentAccountInfo":
    [
        {
            "requestType": "U",
            "institutionNumber": "00000003",
            "merchantId": "89450179",
            "accountTypeId": "063",
            "bankNumber": "341",
            "branchNumber": "002978",
            "rbsAccountNumber": "248111",
            "paymentAccountNumber": "89450179",
            "userId": "100066"
        }
    ]
}
json_body = json.dumps(body)

# token obtido através da API de Token
token = "505f890a-2498-472c-9033-d46e3eb18206"

# data no formato "Unix epoch time" em milissegundos
dt = str(int(time.time() * 1000))

# string alfanumérica gerada pelo usuário
client_request_id = ''.join(random.choice(string.ascii_uppercase +
                                          string.ascii_lowercase +
                                          string.digits) for _ in range(50))

# concatenação de strings
string_to_sign = appkey + client_request_id + dt + json_body

# encriptação da string usando hmac com sha256
encoded_signature = base64.b64encode(hmac.new(secret.encode(),
                                     string_to_sign.encode(),
                                     sha256).digest()).decode()

# string que será enviada como parâmetro "Message-Signature" no header
hmac_auth = encoded_signature

# dicionário "headers" com todos os parâmetros que serão enviados no request
headers = {
    'auth': token,
    'Api-Key': appkey,
    'Timestamp': dt,
    'Message-Signature': hmac_auth,
    'Client-Request-Id': client_request_id,
    'Content-Type': 'application/json'
}

# envio do request e impressão do resultado (status e body)
r = requests.post(url + endpoint, json=body, headers=headers)
print(f'Status: {r.status_code}\n'
      f'Body: {json.dumps(r.json(), indent=4, sort_keys=True, ensure_ascii=False)}')

Output

Status: 200  
    Body: {  
        "processMessage": \[  
            {  
                "accounts": {  
                    "accountInformation": null  
                },  
                "institutionNumber": "00000003",  
                "response": {  
                    "responseInformationList": [  
                        {  
                            "responseCode": "11",  
                            "responseCodeDesc": "Update already executed"  
                        }  
                    ]  
                },  
                "userId": "100066"  
            }  
        ]  
    }

Ejemplo del Script en Shell

Código

    \#!/bin/bash

# appkey extraída da página da aplicação do desenvolvedor
APPKEY="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # Api Key (ou chave publica) gerada pelo Apigee

# senha extraída da página da aplicação do desenvolvedor
SECRET="XXXXXXXXXXXXXXXX" # Chave secreta gerada pelo APIGEE

# url da API
URL="https://int.api.firstdata.com/wsm/merchantinfo/accounts"

# body que será enviado (JSON)
JSON='{"paymentAccountInfo":[{"requestType":"U","institutionNumber":"00000003","merchantId":"89450179","accountTypeId":"063","bankNumber":"341","branchNumber":"002978","rbsAccountNumber":"248111","paymentAccountNumber":"89450179","userId":"100066"}]}'

# data no formato "Unix epoch time" em milissegundos
DATE=`Date +%s%3N` #Data em formato epoch

# string alfanumérica gerada pelo usuário
CLIENT_REQUEST_ID=`head /dev/urandom | tr -dc A-Za-z0-9 | head -c 50 ; echo ''`

# token obtido através da API de Token
TOKEN="cc1b5188-7cc8-4640-b7b5-44113215d8a3"

# concatenação de strings
STRING_TO_SIGN=$APPKEY$CLIENT_REQUEST_ID$DATE$JSON

# encriptação da string usando hmac com sha256
ENCODED_SIGNATURE=$(echo -n $STRING_TO_SIGN | openssl sha256 -binary -hmac $SECRET | base64) #Estamos com suporte ao sha256 somente

# string que será enviada como parâmetro "Message-Signature" no header
HMAC_AUTH=$ENCODED_SIGNATURE

# envio do request com parâmetros no header e o body
curl -H "auth: $TOKEN" -H "Api-Key: $APPKEY" -H "Timestamp: $DATE" -H "Message-Signature: $HMAC_AUTH" -H "Client-Request-Id: $CLIENT_REQUEST_ID" -H "Content-Type: application/json" -d "$JSON" -X POST $URL

Output

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100   462    0   218  100   244    102    114  0:00:02  0:00:02 --:--:--   217
    {"processMessage":[{"institutionNumber":"00000003","userId":"100066","response":{"responseInformationList":[{"responseCode":"11","responseCodeDesc":"Update already executed"}]},"accounts":{"accountInformation":null}}]}