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.
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/{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 '{
"amount": 100,
"name": "Loja 1",
"merchantId": "884dd2a3-e400-4525-8188-2955ef403486",
"dueDate": "2023-04-04T09:28:45.000Z",
"paymentMethods": [
{
"paymentType": "pix",
"expiresIn": 30
}
],
"items": [
{
"name": "Item",
"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>