Sessions

The Sessions API was built to allow the creation of orders and pay them through Malga. In addition to being a tool that can be combined with Malga Checkout to increase the checkout implementation security on the front-end. It's possible to create sessions using Pix, boleto and credit card, being able to pay for each session once.

caution

The sessions API isn't availabe on sandbox environment

Using sessions

To use the Sessions API, first you will have to create a session, with items, amounts and payment methods. After it, using the publicKey returned by the session creation, which has a limited scope, you can acess the payment endpoint and pay it, always once by session. The diagram below shows the flow:

Creating a session

Create and manage sessions using the Session Service.

curl --location --request POST 'https://api.malga.io/v1/sessions' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "amount": 100,
        "isActive": true,
        "capture": true,
        "merchantId": "1b0c6960-702a-4074-95c2-eed2790c16a1",
        "dueDate": "2022-10-25T09:28:45.000Z",
        "description": "Black Friday",
        "statementDescriptor": "JOHN STORE",
        "paymentMethod": [
            {
            "paymentType": "pix",
            "expiresIn": 30
            }
        ],
        "items": [
            {
                "name": "Item 1",
                "description": "Order item",
                "unitPrice": 1000,
                "quantity": 1,
                "tangible": false
            }
        ]
    }'

< HTTP/2 201
{
  "id": "c1db83fa-723c-4e1f-9722-bc19d1be6791",
  "name": "Pedido 1",
  "status": "created",
  "isActive": true,
  "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
  "orderId": "b84b7694-d22f-4083-bee7-c1274b16eb4a",
  "amount": 100,
  "currency": "BRL",
  "capture": true,
  "merchantId": "9930c8d9-a7a8-4039-9faf-3715ad87baf8",
  "dueDate": "2022-10-26T19:32:08.000Z",
  "description": "Pedido Black Friday",
  "statementDescriptor": "JOHN STORE",
  "items": [
    {
      "name": "Item 1",
      "description": "Order item",
      "unitPrice": 1000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "paymentMethods": [
    {
      "paymentType": "pix",
      "expiresIn": 30
    }
  ],
  "createdAt": "2022-10-25T22:49:06.588Z",
  "updatedAt": "2022-10-25T22:49:06.588Z",
  "publicKey": "8be71cdf-01dc-4b1a-823a-4c58be6e4cf1"
}

Paying a session

Pay a session using the Session Service.

curl --location --request POST 'https://api.malga.io/v1/sessions/{id}/charge' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <PUBLIC_KEY_DA_SESSÃO>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
        "amount": 150,
        "currency": "BRL",
        "statementDescriptor": "JOHN STORE",
        "description": "Charge long description",
        "capture": false,
        "orderId": "32c68ff7-902c-408b-b464-cf487c7cda97",
        "paymentMethod": {
            "paymentType": "credit",
            "installments": 1
        },
        "paymentSource": {
            "sourceType": "card",
            "card": {
                "cardNumber": "5261424250184574",
                "cardCvv": "321",
                "cardExpirationDate": "06/2028",
                "cardHolderName": "JOAO DA SILVA"
            }
        }
        }'

< HTTP/2 201
{
   "id": "c1db83fa-723c-4e1f-9722-bc19d1be6791",
   "status": "paid",
   "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
   "orderId": "b84b7694-d22f-4083-bee7-c1274b16eb4a",
   "customerId": "eb70b146-85fd-4100-8fd4-a4dbb647aed3",
   "amount": 100,
   "originalAmount": 100,
   "currency": "BRL",
   "capture": true,
   "merchantId": "9930c8d9-a7a8-4039-9faf-3715ad87baf8",
   "statementDescriptor": "JOHN STORE",
   "paymentMethods": [
      {
         "paymentType": "pix",
         "expiresIn": 30
      }
   ],
   "paymentSource": {
      "sourceType": "card",
      "cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d"
   },
   "transactionRequests": [
      {
         "id": "78601913-a176-4d71-b7e8-abb6fc49a340",
         "idempotencyKey": "fafe857b176e45d6b12e32fcaf228996",
         "providerId": "2c3b57d8-ee43-4b19-bc8a-949a88c51df1",
         "providerType": "STRIPE",
         "transactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob",
         "amount": 100,
         "authorizationNsu": "1cc8391c-f0d5-4b7a-9fcf-653cea26be13",
         "requestStatus": "success",
         "requestType": "authorization",
         "responseTs": "2633ms",
         "createdAt": "2021-08-12T16:08:39.536Z",
         "updatedAt": "2021-08-12T16:08:42.212Z",
         "providerAuthorization": {
            "networkAuthorizationCode": "00",
            "networkResponseCode": ""
         }
      }
   ],
   "createdAt": "2022-10-25T22:49:06.588Z"
}

Integrating MalgaCheckout with sessions

For using the Malga Checkout with the sessions API on a safer way, it's possible to create a session using your back-end and, with a front-end application, using the publicKey with limited scope returned to set up the checkout without exposing the publicKey with higher scope generally used. The diagram below shows the flow:

Using MalgaCheckout with sessions

After creating the session, it's possible to use the id and the publicKey of it to set up the Malga Checkout. To be safer, we recommend don't expose on front-end the publicKey generally used, with higher scope, the front-end application has to access just the session's publicKey.

<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"
  />
  <script
    type="module"
    src="https://unpkg.com/@malga-checkout/core@latest/dist/malga-checkout/malga-checkout.esm.js"
  ></script>
  <title>Malga Checkout Components</title>
</head>
<body>
<main>
  <malga-checkout
    sandbox="false"
    public-key="<SESSION_PUBLIC_KEY>"
    client-id="<YOUR_CLIENT_ID>"
    session-id="<SESSION_ID>"
  >
  </malga-checkout>
</main>

<script>
  const malgaCheckout = document.querySelector('malga-checkout')

  malgaCheckout.addEventListener('paymentSuccess', (data) => {
    // Your specifications here
  })

  malgaCheckout.addEventListener('paymentFailed', (error) => {
    // Your specifications here
  })
</script>
</body>
</html>