Voucher

They are benefit cards that companies provide to their employees, used for the purchase of specific products such as meal vouchers and food vouchers.

Previously, vouchers were only used through card terminals for in-person purchases, but they have become a highly sought-after payment method in online retail.

Accepting them is a way to meet this demand and offer more convenience and freedom to consumers, enabling businesses to diversify their payment options, thereby expanding their potential customer base and increasing conversions.

Voucher Flow

• For a transaction with a card using the Voucher method, it is necessary to provide the payment method as "voucher," source type as "card," and the card's identification details during its creation;
• The charge will be processed on the card through the chosen payment institution, in this case, VR;
• After payment confirmation, the payment provider will transfer funds to the recipient's account;
• Subsequently, the receiving customer may be notified of the successful payment and/or receive a refund if requested.

Payment Status

object	event	description
transaction	authorized	Status sent when payment is authorized
transaction	failed	Status sent when the charge is denied by the financial institution before being authorized, without financial refund
transaction	voided	Status sent when the charge is canceled after being authorized, resulting in a financial refund

Supported providers and vouchers

See the providers that support voucher in our table of providers and supported payment methods.

Full Refund

It is possible to perform a refund for the total amount of the charge. The refund request history can be found in the transactionRequests listing of the charge object.

warning

It is not possible to perform a partial refund in VR provider.

Example of successful voucher transaction

caution

The voucher does not use capture, so it does not need to be provided.

  curl --location '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 '{
            "merchantId": "<MERCHANT_ID>",
            "amount": 100,
            "currency": "BRL",
            "statementDescriptor": "Voucher",
            "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
            "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
            "paymentMethod": {
                "customer": {
                    "name": "Jose das Flores",
                    "identity": "11111111111",
                    "billingAddress": {
                        "zipCode": "01714140",
                        "city": "São Paulo",
                        "state": "SP",
                        "country": "BR",
                        "complement": "complement"
                    }
                },
                "paymentType": "voucher",
                "items": [
                    {
                        "id": "123",
                        "title": "ItemTeste1",
                        "quantity": 1,
                        "unitPrice": 100
                    }
                ]
            },
            "paymentSource": {
                "sourceType": "card",
                "card": {
                    "cardHolderName": "ARACHANE CORTAS",
                    "cardNumber": "6370360004577166",
                    "cardCvv": "527",
                    "cardExpirationDate": "12/2024"
                }
            }
       }'
  < HTTP/2 201
  < content-type: application/json; charset=utf-8
  {
    "id": "97443bea-fb76-43c2-afb1-2cb45abbe673",
    "clientId": "<CLIENT_ID>",
    "merchantId": "<MERCHANT_ID>",
    "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
    "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
    "createdAt": "2023-07-17T19:46:08.597Z",
    "amount": 100,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": "Voucher",
    "capture": true,
    "isDispute": false,
    "status": "authorized",
    "paymentMethod": {
        "paymentType": "voucher"
    },
    "paymentSource": {
        "sourceType": "card"
    },
    "transactionRequests": [
        {
            "id": "e18cf62e-aa43-4db5-abfe-0f63e2749fef",
            "createdAt": "2023-07-17T19:46:08.627Z",
            "updatedAt": "2023-07-17T19:46:10.861Z",
            "idempotencyKey": "5b011a93-2eaf-4b9c-9f22-f3676c7cba74",
            "providerId": "56a83eaf-f9b2-4d2e-97f3-53933331b0e5",
            "providerType": "SANDBOX",
            "transactionId": "f4ae4d32-350d-4135-9b50-b259e937ca03",
            "amount": 100,
            "authorizationCode": "011056",
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": "2212ms"
        }
    ]
}

Example of failed voucher transaction

curl --location '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 '{
        "merchantId": "<MERCHANT_ID>",
        "amount": 100,
        "currency": "BRL",
        "statementDescriptor": "Voucher",
        "capture": true,
        "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
        "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
        "paymentMethod": {
            "paymentType": "voucher"
        },
        "paymentSource": {
            "sourceType": "card",
            "card": {
                "cardHolderName": "ARACHANE CORTAS",
                "cardNumber": "6274160007023102",
                "cardCvv": "527",
                "cardExpirationDate": "12/2024"
            }
        }
     }'
 < HTTP/2 201
 < content-type: application/json; charset=utf-8
 {
    "id": "ef19739f-953b-488e-b653-623b80a88392",
    "clientId": "<CLIENT_ID>",
    "merchantId": "<MERCHANT_ID>",
    "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
    "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
    "createdAt": "2023-07-17T22:09:53.502Z",
    "amount": 100,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": "Voucher",
    "capture": true,
    "isDispute": false,
    "status": "failed",
    "paymentMethod": {
        "paymentType": "voucher"
    },
    "paymentSource": {
        "sourceType": "card"
    },
    "transactionRequests": [
        {
            "id": "e6cad844-ae11-44ab-a83d-e1abfe10ac5c",
            "createdAt": "2023-07-17T22:09:53.542Z",
            "updatedAt": "2023-07-17T22:09:55.048Z",
            "idempotencyKey": "8ef45126-2faa-487c-9367-e8722f5d0d6c",
            "providerId": "56a83eaf-f9b2-4d2e-97f3-53933331b0e5",
            "providerType": "SANDBOX",
            "transactionId": "d00eb5d6-e99f-4c56-a42d-a3d557c27a52",
            "amount": 100,
            "authorizationCode": "011056",
            "authorizationNsu": null,
            "requestStatus": "failed",
            "requestType": "authorization",
            "responseTs": "1413ms"
        }
    ]
}

Example of voucher transaction with partial successfull refund

curl --location 'https://api.malga.io/v1/charges/271a0ef0-5543-4ac9-83e9-f31fc5c174b5/void' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \ \
    --header 'Content-Type: application/json' \
    --data '{
    "amount": 50
    }'

< HTTP/2 201
< content-type: application/json; charset=utf-8   
{
    "id": "271a0ef0-5543-4ac9-83e9-f31fc5c174b5",
    "clientId": "<CLIENT_ID>",
    "merchantId": "<MERCHANT_ID>",
    "description": null,
    "orderId": "orderId",
    "createdAt": "2023-08-16T18:54:01.706Z",
    "amount": 50,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": "Descrição do Pedido",
    "capture": false,
    "isDispute": false,
    "status": "authorized",
    "paymentMethod": {
        "paymentType": "voucher"
    },
    "paymentSource": {
        "sourceType": "card",
        "cardId": "77ed7c5b-a1d7-4ac2-ab3d-0a7e4681f152"
    },
        "transactionRequests": [
            {
            "id": "52984c70-514c-4204-9ee0-3af715eab63b",
            "createdAt": "2023-08-16T18:54:51.434Z",
            "updatedAt": "2023-08-16T18:54:51.434Z",
            "idempotencyKey": null,
            "providerId": "a14c0109-de62-4f09-a613-70567c5697fa",
            "providerType": "PAGARME_V5",
            "transactionId": "or_6ylmd9ZH6Ho50aRo",
            "amount": 50,
            "authorizationCode": "621",
            "authorizationNsu": "27073",
            "requestStatus": "success",
            "requestType": "void",
            "responseTs": "439ms",
            "providerAuthorization": {
                "networkAuthorizationCode": "621",
                "networkResponseCode": "00"
                }
            },
            {
            "id": "266ed9ea-beef-45ef-a145-d2f050777988",
            "createdAt": "2023-08-16T18:54:01.751Z",
            "updatedAt": "2023-08-16T18:54:02.294Z",
            "idempotencyKey": "76162962-1bff-4a56-9f21-c83ad70247a8",
            "providerId": "a14c0109-de62-4f09-a613-70567c5697fa",
            "providerType": "PAGARME_V5",
            "transactionId": "or_6ylmd9ZH6Ho50aRo",
            "amount": 100,
            "authorizationCode": "621",
            "authorizationNsu": "58785",
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": "515ms"
            }
        ]
    }

Example of voucher transaction with successful refund

curl --location 'https://api.malga.io/v1/charges/97443bea-fb76-43c2-afb1-2cb45abbe673/void' \
     --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "amount": 100
    }'
< HTTP/2 201
< content-type: application/json; charset=utf-8   
{
   {
    "id": "a1321f1a-be77-4639-85c8-d0257b2d93af",
    "clientId": "<CLIENT_ID>",
    "merchantId": "<MERCHANT_ID>",
    "description": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
    "orderId": "15ad136a-520b-40d0-9c0e-05ff008b0fa7",
    "createdAt": "2023-07-18T12:52:48.393Z",
    "amount": 0,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": "Voucher",
    "capture": true,
    "isDispute": false,
    "status": "voided",
    "paymentMethod": {
        "paymentType": "voucher"
    },
    "paymentSource": {
        "sourceType": "card",
        "cardId": "692598f6-410b-4f12-b2df-5b3e653c7b9f"
    },
    "transactionRequests": [
        {
            "id": "c6d3cd78-d562-42d8-83b7-4bc6ea362dac",
            "createdAt": "2023-07-18T12:53:16.692Z",
            "updatedAt": "2023-07-18T12:53:16.692Z",
            "idempotencyKey": null,
            "providerId": "bce85756-9016-4483-81b8-b1a2a37c3ac4",
            "providerType": "VR",
            "transactionId": "128898e2ab7d41df99960859",
            "amount": 100,
            "authorizationCode": "011043",
            "authorizationNsu": "128898e2ab7d41df99960859",
            "requestStatus": "success",
            "requestType": "void",
            "responseTs": "2157ms",
            "providerAuthorization": {
                "networkAuthorizationCode": "011043",
                "networkResponseCode": "00"
            }
        },
        {
            "id": "9e01d010-dbb6-497a-bf3c-7c64ff823605",
            "createdAt": "2023-07-18T12:52:48.579Z",
            "updatedAt": "2023-07-18T12:52:52.857Z",
            "idempotencyKey": "205c60c4-c4dc-40c7-8ad5-4339aa61f31a",
            "providerId": "bce85756-9016-4483-81b8-b1a2a37c3ac4",
            "providerType": "VR",
            "transactionId": "128898e2ab7d41df99960859",
            "amount": 100,
            "authorizationCode": "011056",
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": "4236ms"
        }
    ]
}       

Example of voucher transaction with failed refund

curl --location 'https://api.malga.io/v1/charges/4b26b3cf-a9a9-45d7-9629-5a97c1f02b88/void' \
     --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
     --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
     --header 'Content-Type: application/json' \
    --data '{
        "amount": 500
    }'
    
< HTTP/2 422
< content-type: application/json; charset=utf-8 
{
    "error": {
        "type": "unprocessable_entity",
        "code": 422,
        "message": "Transaction failed"
    }
}