Get started
A quick overview of a comprehensive integration with Malga's payment service.
Through this quick guide you will be able to:
- Understand how to use your credentials to access our APIs
- Tokenize card data and save cards in a safe environment for future use
- Create a charge with a tokenized card
- Create a single-time charge with a non-tokenized card
- Test your integration
Environments
Before going into production with your service, test your integration with Malga in our sandbox environment. In this environment the callbacks are mocked, making it possible to validate different scenarios.
Environments | API |
---|---|
Test | sandbox-api.malga.io |
Production | api.malga.io |
Creating an Access Key for the Customer
You must make a call on the Authentication Service from your secret key, requesting the creation of a public key with limited scope.
curl --location --request POST 'https://api.malga.io/v1/auth' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"scope":["tokens"],
"expires": 31104000"
}'
< HTTP/2 201
< content-type: application/json; charset=utf-8
{
"clientId":"<YOUR_CLIENT_ID>",
"publicKey":"<YOUR_PUBLIC_KEY>",
"scope": ["tokens"],
"expires": 31104000,
"createdAt": "20200110 00:00:00"
}
Creating a card token
Perform the tokenization process of sensitive card data client-side using the Token Service, and send the generated token identifier to your backend.
curl --location --request POST 'https://api.malga.io/v1/tokens' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"cardHolderName": "JOSE DAS NEVES",
"cardNumber": "4929564637987814",
"cardCvv": "120",
"cardExpirationDate": "12/2026"
}'
< HTTP/2 201
< content-type: application/json; charset=utf-8
{
"tokenId": "82aba896-9e37-45b6-aa90-d510c9050596"
}
Saving card for recurring purchase
Creates a card from the generated token using the Card Service, receiving a cardId
that can be stored in your system for future purchases.
curl --location --request POST 'https://api.malga.io/v1/cards' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"tokenId": "82aba896-9e37-45b6-aa90-d510c9050596"
}'
< HTTP/2 201
< content-type: application/json; charset=utf-8
{
"id": "148d5db0-f1c3-439f-902d-f1f268086e1d",
"customerId": "82aba896-9e37-45b6-aa90-d510c9050596",
"clientId": "cc0b1e41-2936-45c5-947f-93995ffcdc00",
"expirationDate": "12/2026",
"brand": "visa",
"cvvChecked": true,
"fingerprint": "cbd4a441-c63c-4dee-ac6b-bfa7fa1df818",
"first6digits": "401959",
"last4digits": "9339",
"createdAt": "2012-06-30 23:59:59 +0000",
"status": "active"
}
Creating a charge with tokenized card
Perform a charge with the tokenized credit card data utilizing the Charges Service.
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": "credit",
"installments": 1
},
"paymentSource": {
"sourceType": "card",
"cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d"
}
}'
< 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": "credit",
"installments": 1
},
"paymentSource": {
"sourceType": "card",
"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",
"transactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob",
"providerType": "STRIPE",
"amount": 150,
"authorizationCode": "",
"authorizationNsu": "1616512362092",
"responseCode": "20000",
"requestStatus": "success",
"requestType": "pre_authorization",
"responseTs": null
}]
}
Creating a charge with a single-use card (oneshot)
Perform a charge with credit card data without tokenizing utilizing the Charges Service.
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": "credit",
"installments": 1
},
"paymentSource": {
"sourceType": "card",
"card": {
"cardNumber": "4929564637987814",
"cardCvv": "320",
"cardExpirationDate": "06/2028",
"cardHolderName": "JOAO DA SILVA"
}
}
}'
< 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": "credit",
"installments": 1
},
"paymentSource": {
"sourceType": "card",
"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": "STRIPE",
"amount": 150,
"authorizationCode": "",
"authorizationNsu": "1616512362092",
"responseCode": "20000",
"requestStatus": "success",
"requestType": "pre_authorization",
"responseTs": null
}]
}