Skip to main content

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.

EnvironmentsAPI
Testsandbox-api.malga.io
Productionapi.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
    }]
}