EPX

A loja tem a possibilidade de configurar o roteamento de transações feitas com cartão de crédito no Carat por vários meios de pagamento, um desses meios é o EPX.

Interfaces Carat suportadas para integração

É possível utilizar as seguintes interfaces para a integração com o roteamento EPX:

• Pré Autorização REST
• Pagamento REST
• Cancelamento REST
• Pagamento HTML
• Pré-Autorização HTML
• Cancelamento no Portal do Lojista

Credenciais necessárias

A loja deve obter com o EPX as credenciais listadas abaixo, e repassá-las à Software Express ou fazer o cadastro no Portal do Lojista do Carat.

Parâmetro	Descrição
CUST_NBR	Nível de hierarquia do banco patrocinador do lojista nos sistemas internos do EPX.
MERCH_NBR	Nível de hierarquia de liquidação nos sistemas internos do EPX.
DBA_NBR	Nível de hierarquia de "doing business as" (DBA) nos sistemas internos do EPX.
TERMINAL_NBR	Nível de hierarquia do terminal nos sistemas internos do EPX.

Parâmetros de serviço de criação de transação

Requisição

Parâmetro	Descrição	Formato	Obrigatório
amount	Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto.	< 12 N	Sim
merchant_usn	Número sequencial único enviado pela loja na criação da transação.	< 12 N	Não
order_id	Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade.	< 40 AN	Não
soft_descriptor	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador.	< 30 A	Não
additional_data	Campos adicionais
tax_amount	É um campo de referência que contém o valor do imposto incluído no valor da transação (em centavos).	< 12 N	Não
tax_exempt	Indica se a transação é isenta de impostos. Enviar um dos seguintes valores: <br/>Y - transação é isenta de impostos. <br/>N - transação não é isenta de impostos e necessita do envio do campo tax_amount.	< 1 A	Não
tip_amount	Contém o valor da gorjeta incluída no valor da transação (em centavos).	< 12 N	Não
additional_data<br/>.extra_param	Parâmetros extras
acquirer_params[]	Representa os campos opcionais que o comerciante pode usar para armazenar informações sobre a transação.	< 80 AN	Não
additional_data<br/>.payer	Dados do comprador
born_date	Data de nascimento do comprador, no formato AAAA-MM-DDTHH:MM:SS. Ex.: 1991-01-02T08:30:00	19 N	Não
name	Nome do comprador	< 25 A	Não
surname	Sobrenome do comprador	< 25 A	Não
identification_number	Documento de identificação do comprador (CPF/RG).	< 20 AN	Não
additional_data<br/>.payer<br/>.address	Endereço do comprador
street_name	Nome da rua do comprador. Este campo será enviado ao EPX concatenado com `street_number.	< 30 AN	Não
street_number	Número do endereço do comprador.	< 30 AN	Não
state	Estado do endereço do comprador. Ex.: SP	< 2 A	Não
zip_code	CEP do endereço do comprador	< 9 AN	Não
additional_data<br/>.payer<br/>.phones	Telefone do comprador
number	Contém o número de telefone do cliente.	< 10 N	Não
type	Campo utilizado para diferenciar os tipos de telefone: <br/>6 - Celular <br/> 2 - Comercial <br/> 1 - Residencial	1 N	Não

IMPORTANTE: o EPX NÂO recebe informações relativas a parcelamento e financiamento. Com isso, somente transações à vista são suportadas.

Exemplo de requisição da chamada de criação de transação

curl
--request POST "https://{{url}}/e-sitef-hml/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"2061433036",
   "order_id":"02061433035",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"1",
   "amount":"10000",
   "additional_data":{
      "payer":{
         "address":{
            "zip_code":"12345678",
            "street_number":"123",
            "street_name":"John Street",
            "city":"San Francisco",
            "state":"CA"
         },
         "phones":[
            {
               "number":"12345678901",
               "type":"6"
            }
         ]
      }
   }
}
--verbose

Parâmetros de serviço de efetivação do pagamento e pré-autorização

Requisição

Parâmetro	Descrição	Formato	Obrigatório
card	Dados do cartão
number	Número do cartão do comprador	< 19 N	Sim
barcode_data	Contém os dados do código de barras. Este campo deve ser enviado com o campo acquirer.input_type com valor A e suporta os formatos não criptografados PAN ou TLV Visa. Mais detalhes aqui.	< 100 AN	Não
id	Contém o código que representa a forma de identificação do portador do cartão. Pode receber os seguintes valores: <br/>0 - Portador presente <br/>1 - Portador não presente <br/>M - Portador presente, cartão ilegível	< 1 AN	Não
security_code	Código de segurança do cartão.	< 4 N	Não
expiry_date	Data de vencimento do cartão no formato MMAA.	4 N	Não
issue_number	Número de emissão do cartão de crédito.	< 3 N	Não
issue_date	Data de emissão do cartão de crédito no formato MMAA.	< 4 A	Não
card.crypto	Dados da criptografia do cartão
type	Identifica a encriptação utilizada: <br/> 0 - Usar o campo acquirer.input_type para identificar o formato <br/> 1 - Formato MagTek V2 <br/> 2 Formato 3DES (genérica)	1 N	Não
card.crypto	Dados de EMV do cartão
data	Contém as tags EMV, em transações processadas por meio de chip EMV.	<510 AN	Não
track_1 ou track_2	Contém os dados da tarja magnética do cartão de crédito ou débito. track_1 deve ser usado ao processar uma transação com cartão de crédito, e track_2 deve ser usado se a track_1 estiver indisponível ou ao processar uma transação de débito ou EBT.	<256 AN	Não
acquirer	Dados da adquirente
aci	Identifica características específicas da transação. Pode receber os seguintes valores: <br/>R - Transação é recorrente <br/>P - Transação é uma parcela	1 AN	Não
input_type	Modo de entrada do cartão. Pode receber os seguintes valores: <br/>X - Digitado <br/>A - Código de barras <br/>H - Trilha 1 <br/>D - Trilha 2	1 A	Sim
cash_back_amount	Valor referente ao reembolso (em centavos).	<12 N	Não
reference_number	Número da conta de luz, telefone ou aluguel sendo paga nesta transação.	<25 AN	Não
operator_code	Contém o nome de usuário da pessoa que está enviando a transação.	<25 A	Não
soft_descriptor_2	Campo usado para substituir a seção de cidade/estado do Merchant Descriptor na fatura do portador do cartão.	<40 A	Não
terminal	Dados do terminal
chip_conditions	Campo usado para indicar o motivo da transação de fallback EMV : <br/> 0 - Não aplicável a transações de fallback. Para transações de VSDC deve ser 0 <br/> 1 - A transação foi iniciada a partir de uma tarja magnética com um service code iniciado em 2 ou 6 e a última leitura no terminal VSDC foi uma leitura de chip bem-sucedida ou não foi uma transação de chip. <br/> 2 - A transação foi iniciada em um terminal compatível com chip de uma tarja magnética que contém service code 2 ou 6, e a transação anterior iniciada por esse terminal foi uma leitura de chip malsucedida.	1 N	Não
authentication	Dados de autenticação
authentication.pin	Dados do pin de autenticação
value	PIN Criptografado. Obrigatório quando for digitada a senha online do portador do cartão.	< 64 AN	Não
authentication.pin.crypto	Dados da criptografia do pin de autenticação
ksn	KSN da criptografia do PIN. Obrigatório quando for digitada a senha online do portador do cartão.	< 20 AN	Não

Detalhes do campo barcode_data

Posição	Tamanho	Formato	Descrição
1-3	3	N	Tipo: <br/> - 000 = PAN - Sem criptografia <br/> - 001 = Visa - TLV - Sem criptografia
4-N	Variável	ANS	Dados de código de barra

Exemplo de requisição da chamada de pagamento

curl
--request POST "https://{{url}}/e-sitef-hml/api/v1/payments/1234567890abcdefghijklmnopqrstuvw
xyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"4111111111111111",
      "expiry_date":"1222"
   },
   "acquirer":{
      "input_type":"X"
   }
}
--verbose

Parâmetros de resposta

Parâmetro	Descrição	Formato
balance	Saldo disponível após pagamentos com vouchers (em centavos).	< 12 N
avs_result	Contém a resposta do Address Verification System para a transação solicitada.	1 A
authorization_number	Número de autorização.	< 6 AN
cvv2_response	Contém a resposta CVV2 para a transação solicitada.	1 A
emv_data	Dados EMV.	< 510 AN
tid	Identificação da transação no EPX.	< 20 AN
authorizer_response_code	Código de resposta do EPX.	< 3 AN
authorizer_response_message	Mensagem de resposta do EPX.	< 80 AN
authorizer_date	Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03	16 AN

Exemplo de resposta da chamada de pagamento

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"00",
      "authorizer_message":"EXACT MATCH",
      "status":"CON",
      "nit":"77866520f106682a128d0e2f8ef4c92517c043fa98e3a77a1ffd37ae884ebc47",
      "order_id":"02061433035",
      "customer_receipt":"===== RECEIPT= ====",
      "merchant_receipt":"===== RECEIPT= ====",
      "authorizer_id":"1",
      "acquirer_id":"0",
      "acquirer_name":"EPX",
      "authorizer_date":"02/01/2019T18:15",
      "authorization_number":"053130",
      "merchant_usn":"2061433036",
      "esitef_usn":"190102021262100",
      "tid":"09KGH48QH799RU2QY3V",
      "amount":"10000",
      "payment_type":"C",
      "authorizer_merchant_id":"700010",
      "avs_result":"Y",
      "payment_date":"02/01/2019T18:15"
   }
}