Skip to main content

Integração para Cartão de Crédito#

Sobre este guia#

Esta página ensina como realizar pagamentos com Cartões de crédito através de nossa Direct API. A integração via Direct API é basicamente a mesma para todos os métodos de pagamento, apenas variando o payment_type_code e alguns campos adicionais específicos de cada método.

Se você ainda não está integrado com a Direct API, dê uma olhada neste guia básico. Não tem certeza se a Direct API é a melhor opção para seu e-commerce? Por favor, fale com um de nossos especialistas.

O que você vai precisar#

Antes de iniciar sua integração, certifique-se de ter:

  1. Uma conta em nosso ambiente de testes. Ainda não possui sua conta? Fale com nossa equipe comercial;
  2. creditcard habilitado em sua conta.

Como funciona#

  1. Habilite cartões de crédito em seu dashboard

    O primeiro passo é checar se Cartões de Crédito estão ativos no seu Dashboard EBANX.

    Tudo pronto? Podemos prosseguir para a próxima etapa, caso contrário, entre em contato com nossos especialistas em integração.

  2. Certifique-se de ter todos os campos obrigatórios em sua requisição

    Como ponto de partida, a sua solicitação deve ter o payment_type_code definido como creditcard, assim como o objeto payment.card, definido abaixo.

    Sobre o objeto card:#

    Os campos abaixo são obrigatórios na criação do objeto card.

    CampoDescrição
    card_numberNúmero do Cartão de Crédito.
    card_nameNome do titular do Cartão de Crédito.
    card_due_dateData de validade do cartão (“valid thru”) no formato mm/yyyy.
    card_cvvCódigo de verificação do Cartão.

    Campos Opcionais#

    Os campos abaixo são opcionais na sua solicitação.

    CampoDescrição
    payment.instalmentsNúmero de parcelas. Se você não sabe como funciona o parcelamento, dê uma olhada neste tutorial
    payment.card.auto_captureRelacionado com a pré autorização (Autorização/Captura). Se true, o pagamento será capturado automaticamente pelo EBANX; se false, o pagamento deverá ser capturado pelo merchant por meio da Capture Operation.
    caution

    Tanto o parcelamento quanto a pré autorização podem variar dependendo do país. Confira abaixo as especificidades.

    Particularidades para pagamentos com cartão de crédito#

    Parcelas#

    No Brasil, a quantidade de parcelas aceita (informada no campo installments) pode ser qualquer valor de 1 a 12 para qualquer bandeira de Cartão de Crédito.

    Pré Autorização#

    A pré autorização com cartão de crédito (Autorização e captura, habilitado com o parâmetro auto_capture) está totalmente disponível no Brasil.

    O valor padrão para o parâmetro auto_capture é true. Quando definido como false, o EBANX primeiro emite uma autorização (às vezes chamada de pré-autorização) que deverá ser capturada posteriormente nesta etapa. Pagamentos apenas autorizados terão o status PE (pendente) até sua captura. Após a captura, o status do pagamento será alterado para CO (confirmado).

    note

    Os pagamentos não capturados expiram automaticamente.

    Referência Completa EBANX Direct API

    A referência completa da API para o end-point ws/direct pode ser encontrada aqui. Recomendamos fortemente que você olhe todas as opções disponíveis.

  3. Envie sua solicitação de pagamento para o EBANX

    Agora, basta enviar a sua solicitação de pagamento para o EBANX, abaixo você confere um exemplo:

    curl -X POST 'https://staging.ebanx.com.br/ws/direct' \
    -d 'request_body={
    "integration_key": "your_test_integration_key_here",
    "operation": "request",
    "payment": {
    "name": "José Silva",
    "email": "jose@example.com",
    "document": "853.513.468-93",
    "address": "Rua E",
    "street_number": "1040",
    "city": "Maracanaú",
    "state": "CE",
    "zipcode": "61919-230",
    "country": "br",
    "phone_number": "8522847035",
    "payment_type_code": "creditcard",
    "merchant_payment_code": "3ad1f4096a2",
    "currency_code": "BRL",
    "instalments": 3,
    "amount_total": 100,
    "creditcard": {
    "card_number": "4111111111111111",
    "card_name": "José Silva",
    "card_due_date": "12/2019",
    "card_cvv": "123"
    }
    }
    }'

    Uma solicitação bem sucedida retornará uma resposta JSON semelhante à seguinte. Os pagamentos com cartão de crédito para merchants com verificação de fraude ativada terão o status PE (pendente), enquanto para merchants com verificação de fraude desativada e auto_capture definido como true, o status será CO ( confirmado).

    {
    "payment": {
    "hash": "59ad5f00945fa382ab051651440826da7701533249b3a475",
    "pin": "045868576",
    "merchant_payment_code": "ecc9be4512a",
    "order_number": null,
    "status": "CO",
    "status_date": "2017-09-04 14:11:12",
    "open_date": "2017-09-04 14:11:11",
    "confirm_date": "2017-09-04 14:11:12",
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2017-09-07",
    "instalments": "3",
    "payment_type_code": "visa",
    "details": {
    "billing_descriptor": ""
    },
    "transaction_status": {
    "acquirer": "EBANX",
    "code": "OK",
    "description": "Sandbox - Test credit card, transaction captured"
    },
    "pre_approved": true,
    "capture_available": false
    },
    "status": "SUCCESS"
    }

  4. Capture o pagamento (necessário apenas para o fluxo de duas etapas)

    Capture o pagamento#

    Aplicado apenas à pré autorização

    Esta etapa só é necessária se a solicitação de pagamento foi feita com o parâmetro auto_capture definido como false para capturar um pagamento não capturado já existente.

    Esta é a segunda parte da pré autorização, na primeira etapa você já autorizou o pagamento, que está com o status PE (pendente), e agora só temos que capturá-lo para ter um pagamento CO (confirmado).

    Aqui você pode verificar um exemplo de resposta de uma solicitação de pagamento feita com auto_capture definido como false.

    {
    "payment": {
    "hash": "5ef38bd200a530d9a4c218b054744cb81f9b25c99d4365aa",
    "pin": "025107300",
    "country": "br",
    "merchant_payment_code": "0x0W27D03-T04",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2020-06-24 17:22:26",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "100.00",
    "amount_ext": "99.62",
    "amount_iof": "0.38",
    "amount_ext_requested": "100.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2020-06-27",
    "instalments": "1",
    "payment_type_code": "visa",
    "details": {
    "billing_descriptor": "DEMONSTRATION"
    },
    "transaction_status": {
    "acquirer": "EBANX",
    "code": "OK",
    "description": "Accepted",
    "authcode": "87299"
    },
    "pre_approved": true,
    "capture_available": true
    },
    "status": "SUCCESS"
    }

    Para capturar o pagamento, você deve chamar o end-point ws/capture usando o hash ou merchant_payment_code (destacado na resposta abaixo) da transação autorizada anteriormente.

    Aqui estão dois exemplos, com o hash e merchant_payment_code.

    curl -X POST -G 'https://staging.ebanx.com.br/ws/capture' \
    -d 'integration_key=your_test_integration_key' \
    -d 'hash=5ef38bd200a530d9a4c218b054744cb81f9b25c99d4365aa'
    curl -X POST -G 'https://staging.ebanx.com.br/ws/capture' \
    -d 'integration_key=your_test_integration_key' \
    -d 'merchant_payment_code=0x0W27D03-T04'

    Uma solicitação bem sucedida retornará uma resposta JSON semelhante à seguinte.

    {
    "payment": {
    "hash": "5ef38bd200a530d9a4c218b054744cb81f9b25c99d4365aa",
    "pin": "025107300",
    "country": "br",
    "merchant_payment_code": "0x0W27D03-T04",
    "order_number": null,
    "status": "CO",
    "status_date": "2020-06-24 17:51:08",
    "open_date": "2020-06-24 17:22:26",
    "confirm_date": "2020-06-24 17:51:08",
    "transfer_date": null,
    "amount_br": "100.00",
    "amount_ext": "99.62",
    "amount_iof": "0.38",
    "amount_ext_requested": "100.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2020-06-27",
    "instalments": "1",
    "payment_type_code": "visa",
    "details": {
    "billing_descriptor": "DEMONSTRATION"
    },
    "transaction_status": {
    "acquirer": "EBANX",
    "code": "OK",
    "description": "Accepted",
    "authcode": "87299"
    },
    "pre_approved": true,
    "capture_available": false
    },
    "status": "SUCCESS"
    }
    note

    Os pagamentos não capturados expiram automaticamente.

    API Reference

    A referência completa da API para o end-point ws/capture pode ser encontrada aqui. Recomendamos fortemente que você dê uma olhada em todas as opções disponíveis.

Obtendo Ajuda#

Nós esperamos que este artigo tenha sido esclarecedor, mas caso não tenhamos tirado suas dúvidas você tem as seguintes opções para continuar buscando respostas:

  • Se você ainda não é nosso parceiro e deseja saber mais sobre nossos preços e condições, entre em contato com nossa equipe comercial.
  • Caso você já seja nosso parceiro, entre em contato com nossa equipe de suporte em faleconosco@ebanxpay.com.
Edit this page
Last updated on by Samuell Oliveira