Servicio de creación de transacciones

Esta llamada es necesaria para obtener la URL del método 3DS correspondiente a la tarjeta y la versión más reciente del 3DS admitida, además de crear una transacción en el servidor 3DS que se utilizará en los pasos siguientes del flujo.

Importante: El valor del campo message_version devuelto en la respuesta debe usarse en el paso CREQ (para transacciones de desafío).

Detalles de la llamada#

Recurso: /v2/authentication
Método HTTP: POST
Formato de la solicitud: JSON
Formato la respuesta: JSON
Parâmetros de cabeçalho:

Parámetro	Descrición	Formato	Obligatorio
`merchant_id`	Código de la tienda en el servidor 3DS. Los códigos de producción y certificación serán diferentes.	< 15 AN	SI
`merchant_key`	clave de autentificación de la tienda en el 3DS Server. Las claves de producción y certificación serán diferentes.	< 80 AN	SI
`Content-Type`	Debe ser enviado con el valor `application/json`.	= 15 AN	SI
`Authorization`	Debe ser enviada la firma de autentificación de la tienda en el formato `Bearer {assinatura}`. Ejemplo: `Bearer JHVGytfdgauygdauiw78264284527852897hagdg`.	< 2000 AN	COND.*
`carat_merchant_id`	El código de la tienda Carat debe enviarse solo si el campo `token` se envía en la solicitud	< 15 AN	COND.
`carat_merchant_key`	La clave de autenticación de la tienda Carat debe enviarse solo si el campo `token` se envía en la solicitud	< 80 AN	COND.

* Observación: Por razones de seguridad, para realizar la autentificación de la transacción, se recomienda informar el valor del campo Authorization.
Si la tienda ha registrado su clave pública con el Portal Carat, este campo es obligatorio.
Para más información sobre la futura v3, consulta Quick Start.

Autorizadores disponibles#

ID	Nome
`1`	Visa
`2`	Mastercard
`41`	Elo
`3`	Amex

Generación de la firma#

Para generar el valor que se enviará en el header Authorization, es necesario:

Crear las claves pública y privada
- Consulte la página Autentificación con firma, sección Crear las claves pública y privada.
- Envíe sólo la clave pública a nuestro equipo de soporte, que asociará internamente esta clave al registro de su tienda.
Siga las instrucciones de generación de firmas descritas en la página Autentificación con firma, sección Algoritmo de firma, a excepción de la subsección Segunda parte (payload), que será diferente en este caso - ver más detalles a continuación.

Payload#

Es posible generar la firma utilizando 3 payloads diferentes:

El payload usando tarjeta para esta funcionalidad debe tener el siguiente formato:

{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}

El payload usando token para esta funcionalidad debe tener el siguiente formato:

{
   "cardholder":{
      "acct":{
         "token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}

[Futura v3] El payload usando tarjeta encriptada para esta funcionalidad debe tener el siguiente formato:

{
   "cardholder":{
      "acct":{
         "encrypted_number":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}

Payload Base64:

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M

Composición del payload#

Parámetro	Descrición	Formato	Obligatorio
`merchant_id`	Código de la tienda en el Portal Carat.	= 15 AN	SI
`merchant_key`	Clave de autentificación de la tienda en el Portal Carat.	< 80 AN	SI
`cartao`	Número de tarjeta del comprador (PAN), el campo `tarjeta` o `token` siempre debe enviarse en la carga útil.	< 19 AN	COND
`token`	HASH de una tarjeta almacenada en Carat, el campo `tarjeta` o `token` siempre debe enviarse en la carga útil	= 88 AN	COND
`timestamp`	Representación en milisegundos del momento de generación de la firma. Destacando que el campo timestamp tiene un límite de validez de 10 minutos.	< 13 N	SI

Ejemplos#

Abajo estan algunos ejemplos de llamada al servicio de creación de transacciones utilizando la herramienta cURL.

Solicitud con número de tarjeta:

Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br

curl 
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}
--verbose

Respuesta:

{
  "three_ds_method_url": "https://www.example.com",
  "three_ds_server": {
    "trans_id": "12341234-1234-1234-1234-123412341234",
    "status": "NEW"
  },
  "acs": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  },
  "device_channel": "02",
  "ds": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  },
  "message_version": "2.2.0"
}

Solicitud con token: Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br

curl 
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--header "carat_merchant_id: yyyyyyyyyyyyyyy"
--header "carat_merchant_key: zzzzzzzzzzzzzz"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
   "cardholder":{
      "acct":{
         "token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}
--verbose

Respuesta:

{
    "three_ds_method_url": "https://www.example.com",
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "NEW"
    },
    "acs": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "device_channel": "02",
    "ds": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
   "message_version": "2.2.0"
}

[Futura v3] olicitud con número de tarjeta encriptado: Para usar este ejemplo, no olvide definir la variable {{url}} con el valor
esitef-homologacao.softwareexpress.com.br

curl 
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant-id: xxxxxxxxxxxxxxx" 
--header "merchant-key: xxxxxxxxxxx"
--header "Client-Request-Id: a5179032-71cf-4320-b171-69629b1db4b8"
--header "Auth-Token-Type: HMAC"
--header "Authorization: {HMAC signature}"
--header "api-key: {HMAC key}"
--data-binary
{
   "cardholder":{
      "acct":{
         "encrypted_number":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}
--verbose

Respuesta:

{
    "three_ds_method_url": "https://www.example.com",
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "NEW"
    },
    "acs": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "device_channel": "02",
    "ds": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
   "message_version": "2.2.0"
}

Errores HTTP 400#

Requisición con número de tarjeta fuera del rango de tarjetas soportadas (código de retorno de error 305 y status INV): Otras entradas inválidas también resultarán en el status INV.

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1111120000001000"
      }
   },
   "brand_id":"2"
}
--verbose

Respuesta código de retorno de error 305 y status INV:

{
  "three_ds_server": {
    "trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
    "status": "INV"
  },
  "device_channel": "02",
  "error": {
    "code": "305",
    "component": "S",
    "description": "Cardholder Account Number is not in a range belonging to Issuer",
    "detail": "acctNumber"
  }
}

Respuesta a un error durante la comunicación con DS - Status ERR

{
  "three_ds_server": {
    "trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
    "status": "ERR"
  },
  "device_channel": "02",
  "error": {
    "code": "405",
    "component": "S",
    "description": "DS communication failure",
    "detail": "acctNumber"
  }
}

Respuesta para cuando DS retorna un mensaje de error - Status ERM

{
  "three_ds_server": {
    "trans_id": "9f289031-3f9e-4874-afa8-db6fb7a4207c",
    "status": "ERM"
  },
  "device_channel": "02",
  "error": {
    "code": "",
    "component": "S",
    "description": "3DS Server received an error message from DS",
    "detail": "acctNumber"
  }
}

Parámetros de solicitud#

En la tabla siguiente se describen los parámetros de solicitud del servicio de creación de transacciones:

Parámetro	Descrición	Formato	Obligatorio
`brand_id`	ID da la tarjeta. más información.	= 4 N	SI
cardholder.acct
`number`	Número de tarjeta del comprador, el campo `encrypted_number`, `number` o `token` siempre debe enviarse en la solicitud	< 19 N	COND
`token`	HASH de una tarjeta almacenada en Carat, siempre se debe enviar el campo `encrypted_number`, `number` o `token` en la solicitud	= 88 AN	COND
`encrypted_number`	[v3] Número encriptado de tarjeta del comprador, siempre se debe enviar el campo `encrypted_number`, `number` o `token` en la solicitud		COND
message
`version`	Versión del mensaje 3DS: `2.1.0` ou `2.2.0`.	< 8 AN	NO

Parámetros de respuesta#

En caso de éxito, el código de respuesta HTTP será 201. Cualquier otro código debe ser interpretado como un error. En la tabla siguiente se describen los parámetros de respuesta del servicio de creación de transacciones:

Parámetro	Descrición	Formato
`three_ds_method_url`	URL do frame invisible que se mostrará en el navegador del comprador	< 256 AN
`device_channel`	Canal del dispositivo. Saiba mais.	< 2 N
`message_version`	Versión de transacción (esta versión debe usarse en la solicitud de CRes)	< 8 AN
three_ds_server
`trans_id`	ID de la transacción 3DS Server	< 8 AN
`status`	Status no 3DS Server. más información.	= 3 AN
acs.protocol_version
`start`	Versión más antigua del protocolo 3DS soportada por ACS	< 8 AN
`end`	Versión más reciente del protocolo 3DS soportada por ACS	< 8 AN
ds.protocol_version
`start`	Versão mais antiga de protocolo 3DS suportada pelo DS	< 8 AN
`end`	Versão mais recente de protocolo 3DS suportada pelo DS	< 8 AN
error
`code`	Código de error. más información.	< 3 N
`component`	Indica cual componente identificou el error. `C` = 3DS SDK `S` = 3DS Server `D` = DS `A` = ACS	= 1 AN
`description`	Descripción del error	< 2048 AN
`detail`	Detalles del error	< 28 AN

Home

Detalles de la llamada#

Autorizadores disponibles#

Generación de la firma#

Payload#

Composición del payload#

Ejemplos#

Errores HTTP 400#

Parámetros de solicitud#

Parámetros de respuesta#