Credit Card

Malga performs the role of a payment intermediary, but does not perform the financial clearance, therefore it is necessary for the Malga’s customer to have an account at a financial institution that is part of the financial system. Thus, we receive the data sent by the customer in the charges’ API and communicate with acquires and PSPs.

Payment Flow

• To create a transaction with credit card the customer simply informs the payment method as credit when creating a charge, and card's holder data;
• A charge is make in the card by the payment provider choosed.
• After confirmation of the payment, the payment provider will transfer the funds to the payee's account.
• Subsequently the payee customer will be notified that the payment has been made and the charges were successfully completed.

Supported payment providers

ProviderType	Description
PAGSEGURO	PagSeguro
PAGARME	Pagar.me
CIELO	Cielo
STRIPE	Stripe
ZOOP	Zoop
REDE	Rede
BRAINTREE	Braintree
KLAP	Klap
MERCADO_PAGO	Mercado Pago
PLUG_SANDBOX	Simulator in sandbox enviroment

A credit card charge when created is registred as authorized, pre_authorized or failed.

É possível realizar estorno total ou parcial para pagamentos do tipo PIX, sendo possível realizar pre-autorização e captura de cobranças deste tipo.

Status changes notification

object	event	description
transaction	pending	Event sent when charge is created on Malga
transaction	pre_authorized	Event sent when charge is pre authorized, reserving the balance
transaction	authorized	Event sent when charge is authorized
transaction	failed	Event sent when charge is denied by financial institution before been authorized, without refund
transaction	canceled	Event sent when charge is canceled before been captured, without financial refund
transaction	voided	Event sent when charge is canceled after been captured, with financial refund
transaction	charged_back	Event sent when charge is contested by fraud suspect or commercial disagreement

Charge example

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
    }]
}

Pre authorization and capture

In the credit card payment flow, it is possible to perform an authorization that secures the amount charged for a later capture, or you can already authorize the payment in a definitive manner. Some merchants choose not to capture the transaction immediately in order to be able to run their own anti-fraud program after securing the balance on the card, and depending on the result of the analysis, confirm or not the transaction. The advantage of reversing a transaction that has not yet been "captured" is that the reversal is presented immediately in the buyer's bank statement, in some cases when you try to reverse a transaction already captured, it can take up to 30 days for the reversal to appear on the bank statement, so many merchants choose not to capture automatically and do it manually later.

The capture flag is used to indicate whether the transaction should be captured or not.

In our API, if you send the capture: false attribute, we will return the authorized transaction (balance secured on the card) with pre_authorized status and you will need to make a request to the Capture Service to manually force the capture of the transaction and release it for clearance on the provider's account. If the transaction is not captured within 7 days the acquirer can automatically undo the transaction.

If you send the attribute capture: true we will return the authorized transaction with authorized status, no further action is required, the transaction is already released for clearance at the acquirer and does not need to call the capture service.

Partial Refund

In the card payment flow, it is possible to perform a full or partial charge refund. In the case of partial refund, the merchant chooses to perform a reversal of an amount lower than the total value of the sale, and the refund of the partial amount reversed is made to the buyer, while the remaining charges remain as authorized for clearance in behalf of the merchant.

To perform a partial refund, you simply submit in the void request an amount that is less than the original transaction amount, and this reversal amount is the amount to be refunded. Once the partial reversal request is approved by the card issuer, the transaction amount is then updated to the residual amount of the transaction after the refund (charge amount - refunded amount),

caution

The originalAmount attribute of the charge object stays as the original amount authorized in the transaction, it is the initial amount of the transaction when approved. The amount attribute of the charge object changes with each partial refund request, maintaining the residual balance to be received by the merchant.

It is important to note that several partial refunds requests can be made for the same transaction, and in each request our system checks if the amount to be reversed, (the amount sent in the void request), is less than or equal to the residual amount of the transaction, not being possible to reverse a higher amount. The archive of reversal requests can be found in the transactionRequests listing of the charge object.

The transaction status will remain authorized or pre_authorized as long as there is still an amount to be paid to the merchant, and will change to voided only when the refund resets the amount to be received from the merchant to zero.

Charging in other Currencies

Malga supports charging in wide variety of currencies, you can handle payment in the buyer preferred currency.

If the chosen currency be different of the buyer card currency additional fees can be charged.

Send the currency in the field currency of charge object, BRL is the default value when not informed.

info

The currency acceptance must be conditioned by the payment provider, there isn't all provider that support multiple currency charge. Check the availability with Malga team.

Attached you find the supported currencies table