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: Y - transação é isenta de impostos. 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.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.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.payer.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.payer.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: 6 - Celular 2 - Comercial 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#
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: 0 - Portador presente 1 - Portador não presente 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: 0 - Usar o campo acquirer.input_type para identificar o formato 1 - Formato MagTek V2 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: R - Transação é recorrente P - Transação é uma parcela | 1 AN | Não |
input_type | Modo de entrada do cartão. Pode receber os seguintes valores: X - Digitado A - Código de barras H - Trilha 1 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 : 0 - Não aplicável a transações de fallback. Para transações de VSDC deve ser 0 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. 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: - 000 = PAN - Sem criptografia - 001 = Visa - TLV - Sem criptografia |
| 4-N | Variável | ANS | Dados de código de barra |
Exemplo de requisição da chamada de pagamento#
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 |