Request Operation

Esta página explica como processar pagamentos usando integração com a Payment Page EBANX. Com este método o cliente será redirecionado à página do EBANX para inserir os dados.

Endpoints

Endpoints	HTTP Method	Response
https://api.ebanx.com.br/ws/request https://staging.ebanx.com.br/ws/request	POST	application/json

Parâmetros de Requisição

Campo	Tipo	Descrição
integration_key Mandatório	String max 100	Sua chave de integração única e secreta
name Mandatório	String max 100	Nome do cliente.
email Mandarório	String max 100, email	Endereço de email do cliente.
currency_code Mandatório	String fixo 3	Código da moeda do pagamento, três letras ISO 4217. Moeda suportada: BRL
amount Mandatório	Float	O valor na moeda especificada em (currency_code). Ex: 100.50
merchant_payment_code Condicional	String max 40	ID do pagamento gerado pelo merchant. Mandatório se hash não for informado.
order_number Opcional	String max 40	O número identificador do pedido definido pelo merchant. Você pode ter vários pagamentos com o mesmo número de pedido.
payment_type_code Mandatório	String max 32	Código do método de pagamento. Os códigos suportados são: amex: cartão de crédito American Express. boleto: Boleto bancário. discovery: cartão de crédito Discovery. elo: Cartão de crédito Elo. hipercard: cartão de crédito Hipercard. mastercard: cartão de crédito MasterCard. visa: cartão de crédito Visa. creditcard: Cartão de crédito. debitcard: cartão de débito. Pode ser escolhido mais de um tipo, basta enviar separados por vírgula sem espaços. Ex: boleto, creditcard.
user_value_1, user_value_2, user_value_3, user_value_4, user_value_5 Opcional	String max 20	Parâmetros opcionais que podem ser usados pelo merchant para associar informações adicionais ao pagamento. Esses parâmetros serão anexados à response_url quando a transação for concluída.
notification_url Opcional	String max 2000	A URL para enviar notificações do pagamento. Se esse campo for preenchido, o EBANX irá notificar usando esta URL ao invés da configurada. Exemplo: https://notify.example.com/
bypass_boleto_screen Opcional	Boolean	Se este parâmetro for definido como true, o EBANX não exibirá a página de pagamento concluído e redirecionará o cliente direto para a URL de resposta, onde o estabelecimento deverá fornecer todas as informações do pagamento. Caso o parâmetro não seja fornecido ou seu valor não seja true, a página de pagamento concluído será exibida. Isso pode ser usado nos casos em que o merchant fornecerá todas as informações do pagamento em sua página.
zipcode Opcional	String max 8	CEP do cliente no formato: 00000000. Se for informado, será exibido na Payment Page EBANX.
address Opcional	String max 100	Endereço do cliente (nome da rua). Se for informado, será exibido na Payment Page EBANX.
street_number Opcional	String max 30	Número da residência do cliente. Se for infomado, será exibido na Payment Page EBANX.
city Opcional	String max 80	Cidade do cliente. Se for informado, será exibido na Payment Page EBANX.
state Opcional	String max 5	Estado/Província do cliente. Se for informado, será exibido na Payment Page EBANX.
country Mandatório	String fixo 2	O código do país do cliente, duas letras. O código disponível é: br : Brasil.
phone_number Opcional	String max 15	Número de telefone do cliente. Se for informado, será exibido na Payment Page EBANX.
due_date	String fixo 10	Data de vencimento dos recibos para pagamentos por boleto no formato dd/mm/aaaa. A data de vencimento máxima dependerá das configurações da sua merchant account e será baseada na hora local do país onde o pagamento foi gerado.
sub_acc_name Opcional	String max 32	O nome da subconta.
sub_acc_image_url Opcional	String max 200	A URL do logotipo da subconta. OBS: DEVE ser uma URL HTTPS, caso contrário, você receberá uma mensagem de erro.
instalments Opcional	String max 5	Número ou intervalo de parcelas. OBS: Se você está enviando um intervalo, deve estar no formato “X-Y”. Exemplo: “1-6”.

As requisições retornarão um objeto JSON com os dados do pagamento. Os parâmetros de resposta variam de acordo com o método de pagamento escolhido:

Parametros de resposta

Campo	Tipo	Descrição
status	String	O status da solicitação (SUCCESS ou ERROR).
payment	JSON	Um objeto JSON com as informações do pagamento.
payment.hash	String max 48, único	O hash de pagamento (identificador único EBANX).
payment.bin	String max 41, único	O BIN de pagamento (identificador único do cliente EBANX).
payment.country	String fixo 2, único	Código do país do pagamento.
payment.merchant_payment_code	String max 40	ID do pagamento gerado pelo merchant.
payment.order_number	String max 40	O número identificador do pedido definido pelo merchant. Você pode ter vários pagamentos com o mesmo número de pedido.
payment.status	String fixo 2	O status do pagamento. Os seguintes status estão disponíveis: OP: o cliente ainda não preencheu os detalhes de pagamento no Checkout EBANX. Poderá ser alterado para CA ou PE. PE: o pagamento está pendente de confirmação. Poderá ser alterado para CA ou CO. CO: o pagamento está confirmado (pago). CA: o pagamento está cancelado.
payment.status_date	String fixo 19, UTC	A data e hora da última mudança de status.
payment.open_date	String fixo 19, UTC	A data e hora da criação do pagamento.
payment.confirm_date	String fixo 19, UTC	A data e hora da confirmação do pagamento.
payment.transfer_date	String fixo 19, UTC	A data e hora da liquidação do pagamento.
payment.amount_br	Float	O valor na moeda local.
payment.amount_iof	Float	O valor do imposto na moeda local.
payment.amount_ext	Float	O valor na moeda original.
payment.currency_rate	Float	A taxa de câmbio usada no pagamento.
payment.currency_ext	String fixo 3, ISO 4217	Código de três letras da moeda original.
payment.due_date	String fixo 10, dd/mm/aaaa	Data de expiração do pagamento (aplicável apenas para alguns métodos).
payment.instalments	Int 1-12	Quantidade de parcelas do pagamento, o valor padrão é 1.
payment.payment_type_code	String max 32	O código do método de pagamento. Os códigos suportados são: - creditcard - debitcard - boleto
payment.details	JSON	Objeto JSON com os detalhes do pagamento.
payment.details.billing_descriptor	String	Mensagem que será exibida no descritivo da fatura do cliente.
payment.transaction_status	JSON	Um objeto JSON com dos dados da transação do pagamento com cartão de crédito.
payment.transaction_status.acquirer	String max 16	O adquirente que processou a transação.
payment.transaction_status.code	String max 7	O código de status da transação: OK: o valor da transação foi aprovado. NOK: O adquirente não aprovou a transação. O cliente deve entrar em contato com o emissor para verificar se há algum problema com seu cartão de crédito. RETRY: Algo deu errado com o processo. Você pode tentar novamente usando os mesmos dados. Recomendamos que sejam feitas mais 3 tentativas em diferentes momentos (a segunda tentativa 2 horas após a primeira, etc). Você pode ver sobre esses status aqui
payment.transaction_status.description	String max 500	A descrição do código de status que é retornado do adquirente.
payment.transaction_status.authcode	String max 40	Código de autenticação da transação no adquirente.
payment.pre_approved	Boolean	Flag que mostra se um pagamento foi pré-aprovado pelo adquirente do cartão de crédito.
payment.capture_available	Boolean	Flag que mostra se um pagamento está pronto para ser capturado. Aplica-se apenas a cartões de crédito quando auto_capture está definido como false. Algumas observações sobre este atributo: Um pagamento só pode ser capturado se o valor do pre_approved for true, o que significa que o pagamento foi pré-aprovado pelo adquirente do cartão de crédito. Antes da captura, um pagamento autorizado tem o status PE (pendente). Após a captura, o status muda para CO (confirmado). Um pagamento só pode ser capturado se o status for PE (pendente) * Os pagamentos devem ser capturados em 4 (quatro) dias, caso contrário, são cancelados automaticamente. NOTA: Pode ser alterado em até 5 (cinco) dias.
payment.redirect_url	String variável	A URL para onde o cliente deve ser redirecionado. Aplica-se a alguns métodos de pagamento usando a API Direta.
payment.boleto_url	String variável	A URL do boleto.
payment.boleto_barcode	String max 47	O número do código de barras do boleto.
payment.refunds	JSON	Um Array contendo objetos que representam um reembolso vinculado a este pagamento. Este objeto só estará presente se for emitido um reembolso.
payment.refunds.id	Int	O ID do reembolso no EBANX.
payment.refunds.merchant_refund_code Opcional	String max 20	ID do reembolso gerado pelo merchant.
payment.refunds.status	String fixo 2	O status do reembolso: RE (Solicitado): O reembolso foi solicitado e está aguardando ser processado. Poderá ser cancelado enquanto tiver esse status. PE (Pendente): O reembolso está sendo processado. Não poderá ser cancelado. CO (confirmado): o reembolso foi processado e o dinheiro devolvido ao cliente. CA (cancelado): o reembolso foi cancelado.
payment.refunds.request_date	String fixo 19, data UTC	A data e hora da solicitação do reembolso.
payment.refunds.pending_date	String fixo 19, data UTC	A data e hora que os dados do cliente foram recebidos
payment.refunds.confirm_date	String fixo 19, data UTC	A data e a hora que o dinheiro foi transferido para o cliente.
payment.refunds.amount_ext	Float	O valor reembolsado na moeda original.
payment.refunds.description	String max 1500	Descrição do motivo do reembolso.
payment.chargeback	JSON	Objeto JSON com as informações do chargeback vinculado ao pagamento. Este objeto só estará presente se um chargeback for emitido.
payment.chargeback.create_date	String fixo 19, data UTC	A data e hora que o chargeback foi importado para o sistema.
payment.chargeback.chargeback_date	String fixo 19, data UTC	A data e hora que o chargeback foi criado pelo adquirente em nome do cliente.
payment.chargeback.description	String max 1500	Descrição do chargeback.
payment.chargeback_credit	Boolean	Flag que indica se um estorno de chargeback foi gerado.