> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de integração

Antes de transacionar com Apple Pay na Malga, você precisará gerar alguns certificados disponibilizados pela Apple que permitirão que a Malga possa processar seus pagamentos, sendo eles:

* [Certificado de identidade de comerciante;](/documentations/payment-methods/apple-pay/certificates-setup#criando-um-certificado-de-identidade-do-merchant)

* [Certificado de processamento de pagamento.](/documentations/payment-methods/apple-pay/certificates-setup#criando-um-certificado-de-processamento-de-pagamento)

## Configurando o Apple Pay na Malga e no seu provedor

O certificado de processamento de pagamento deverá ser enviado no suporte do time Malga, enquanto que o certificado de identidade de comerciante deverá ser enviado para o seu provedor, também via suporte. Com os dois configurados adequadamente na Malga e no provedor, você já poderá enviar transações Apple Pay via Malga, configurando seu fluxo inteligente via Dashboard da maneira desejada.

## Criando uma cobrança Apple Pay

* Para criar uma transação com Apple Pay basta o cliente informar o meio de pagamento *apple\_pay* na criação de uma cobrança e os tokens provenientes da wallet;

* Uma cobrança é feita no cartão através do provedor configurado no fluxo inteligente;

* Após confirmação do pagamento, o provedor enviará uma notificação para a Malga informando que o pagamento foi realizado;

* Posteriormente o cliente recebedor será notificado de que o pagamento foi efetuado e a cobrança finalizada com sucesso.

Realize uma cobrança a partir dos dados do cartão de crédito sem tokenizar usando o [Serviço de Charges](/api-reference/charges/realizar-nova-cobranca).

<Accordion title="Requisição para criar cobrança com Apple Pay">
  ```bash theme={null}
    curl --location --request POST 'https://api.malga.io/v1/charges' \
      --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
      --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
        "amount": 150,
        "currency": "BRL",
        "statementDescriptor": "Pedido #231 loja joão",
        "capture": false,
        "paymentMethod": {
          "paymentType": "apple_pay",
          "installments": 1
        },
        "paymentSource": {
          "sourceType": "wallet",
          "walletPayment": "credit",
          "paymentData": {
            "data": "/ZCUzCmr236kDnnXb9cZsvG1JJOqe8GOuRDfCgJ...7haAXX9ml5c7eCIf+IQa1MSGUZYgawepPy",
            "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDTAL...s9BerKDnL1zoEcmcybKzgAAAAAAAA==",
            "header": {
              "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKo...ixBMa1KGjnGapsQih+Kdbg2fA=="
            },
            "version": "EC_v1"
          }
        }
      }'

    < HTTP/2 201
    < content-type: application/json; charset=utf-8
    {
      "id": "10ad53ec-76bb-41d2-a0fe-7513f8f50a8f",
      "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
      "clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
      "createdAt": "2021-03-23T15:12:38.379Z",
      "amount": 150,
      "originalAmount": 150,
      "currency": "BRL",
      "statementDescriptor": "Pedido #231 loja joão",
      "capture": false,
      "status": "pre_authorized",
      "paymentMethod": {
        "paymentType": "apple_pay",
        "installments": 1
      },
      "paymentSource": {
        "sourceType": "wallet",
        "cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d"
      },
      "transactionRequests": [{
          "id": "5e506984-318a-4390-b87a-a3bd9b91d357",
          "updatedAt": "2021-03-23T15:12:42.799Z",
          "createdAt": "2021-03-23T15:12:38.392Z",
          "idempotencyKey": "4271e96e-8c2f-4857-a122-279613bc4747",
          "requestId": null,
          "providerId": "72cc1ff1-5f6e-4eb2-9cc5-6a3a85525e4b",
          "providerType": "CIELO",
          "amount": 150,
          "authorizationCode": "",
          "authorizationNsu": "1616512362092",
          "responseCode": "20000",
          "requestStatus": "success",
          "requestType": "pre_authorization",
          "responseTs": null
      }]
  }
  ```
</Accordion>

<Info>
  Os dados que são enviados dentro da `paymentData` são disponibilizados pelos SDK's de carteira digital, podendo ser, na web, o [Payment Request API](https://www.w3.org/TR/payment-request/) ou o [Apple Pay JS API](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api) e, no mobile, com o [PassKit](https://developer.apple.com/documentation/passkit/offering-apple-pay-in-your-app).
</Info>

Quando criada na Malga, a cobrança do tipo Apple Pay `credit`:

* É registrada com status `authorized`, `pre_authorized` ou `failed`;

* É possível realizar o estorno total ou parcial da cobrança;

* É possível realizar a pré-autorização e captura da cobrança.

## Notificação de alteração de status

| objeto        | evento            | descrição                                                                                                                  |
| ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| *transaction* | *pending*         | Evento enviado quando a cobrança é criada na Malga                                                                         |
| *transaction* | *pre\_authorized* | Evento enviado quando é pre-autorizado o pagamento, com reserva de saldo                                                   |
| *transaction* | *authorized*      | Evento enviado quando é autorizado o pagamento                                                                             |
| *transaction* | *failed*          | Evento enviado quando a cobrança é negada pela instituição financeira antes de ter sido autorizada, sem estorno financeiro |
| *transaction* | *canceled*        | Evento enviado quando a cobrança é cancelada antes ter sido capturada, não produzindo um estorno financeiro                |
| *transaction* | *voided*          | Evento enviado quando a cobrança é cancelada após ter sido autorizada, produzindo um estorno financeiro                    |
| *transaction* | *charged\_back*   | Evento enviado quando a cobrança é contestada por fraude                                                                   |
|               |                   |                                                                                                                            |

## Pré-autorização e captura

No fluxo de pagamentos por cartão é possível realizar uma autorização que reserva o saldo e fica pendente de uma captura posterior, ou você pode já autorizar o pagamento de maneira definitiva. A vantagem de estornar uma transação que ainda não tenha sido "capturada" é que o estorno é feito imediatamente na fatura do comprador, em alguns casos quando você tenta estornar uma transação já capturada pode levar até 30 dias para constar o estorno na fatura, por isso muitos lojistas optam por não capturar automaticamente e fazer isso manualmente depois.

O flag de `capture` serve para indicar se a transação deve ou não ser capturada.

Na nossa API caso você envie o atributo `capture: false` iremos retornar a transação autorizada (saldo reservado no cartão) com status `pre_authorized` sendo necessário que você faça um request no [Serviço de Captura](/api-reference/charges/capturar-cobranca-pre-autorizada) para forçar manualmente a captura da transação e liberar para liquidação na conta do provedor. Se a transação não for capturada em 7 dias o adquirente pode desfazer automaticamente a transação.

Caso você envie o atributo `capture: true` iremos retornar a transação autorizada com status `authorized`, não sendo necessário mais nenhuma ação, a transação já fica liberada para liquidação no adquirente e não precisa chamar o Serviço de Captura.

Em nosso dashboard, também é possível *capturar*.

## Estorno Total ou Parcial

No fluxo de pagamento por Apple Pay, é possível realizar um estorno no valor total ou parcial da cobrança. No caso de estorno parcial, o lojista opta por realizar um estorno com valor inferior ao valor da venda, sendo feito o reembolso do valor parcial estornado para o comprador, permanecendo a cobrança como autorizada para liquidação do valor restante para o lojista.

Para realizar um estorno parcial, basta enviar na [requisição de void](/api-reference/charges/estornar-cobranca-aprovada) um `amount` inferior ao valor original da transação, sendo este `amount` do estorno o valor a ser estornado. Uma vez aprovada a solicitação de estorno parcial junto ao emissor do cartão, o `amount` da transação é então atualizado para o valor residual da transação após o estorno (valor da cobrança - valor estornado),

<Warning>
  O atributo `originalAmount` do objeto `charge` se mantém como o valor
  originalmente autorizado na transação, é o valor inicial da transação quando
  aprovada. Já o atributo `amount` do objeto `charge` é alterado a cada
  solicitação de estorno parcial, mantendo o saldo residual a receber pelo
  lojista.
</Warning>

Importante ressaltar que podem ser realizadas diversas requisições de estorno parcial para uma mesma transação, sendo que a cada requisição nosso sistema verifica se o valor a ser estornado, (o valor enviado na requisição de `void`), é menor ou igual ao valor residual da transação, não sendo possível estornar um valor superior. O histórico de requisições de estorno pode ser encontrado na listagem de `transactionRequests` do objeto `charge`.

O status da transação permanecerá como `authorized` ou `pre_authorized` enquanto restar valor a ser pago ao lojista, sendo alterado para `voided` somente quando o estorno zera todo o valor a receber do lojista.

<Info>
  Embora raro, um reembolso pode falhar após você ter recebido um webhook de REEMBOLSO com success: true. Um webhook de REEMBOLSO bem-sucedido significa que nossas validações foram bem-sucedidas e enviamos a solicitação de reembolso para o esquema do cartão. No entanto, o esquema do cartão ainda pode rejeitar o reembolso. Isso pode acontecer mesmo alguns dias após você enviar a solicitação de reembolso.

  Na maioria das vezes, a Adyen pode corrigir o problema, para que o comprador eventualmente receba os fundos. Às vezes, no entanto, você precisa tomar medidas por conta própria. Para saber por que um reembolso pode falhar e o que, se necessário, você precisa fazer em cada caso, consulte Reembolsos falhados.
</Info>

## Tratando erros na captura e estorno

As modificações feitas em uma cobrança para fins de estorno total, estorno parcial, ou captura podem retornar com erro no provedor. A fim de garantir o correto tratamento dos casos de exceção retornado pelos provedores nestas operações, nossa API, ao receber erro na captura/estorno, retorna HTTP Status Code 201, sendo criado um novo transactionRequest com o status `failed`, porém não é modificado o status original da transação. **É recomendado que você verifique o status do objeto charge retornado, ou o status do primeiro objeto da lista de transactionRequests para se certificar que a operação foi realizada com sucesso.**