NuPay

NuPay is an online payment solution provided by Nubank which aims to reduce operational costs and improve customer experience in purchases with installment in a credit cardless and frictionless manner. To pay using NuPay the buyer must be a Nubank client and must possess at least a credit card issued by the institution in his name.

Malga performs the role of a payment intermediary and as such does not perform the financial clearance, therefore it is necessary to have an active account in NuPay for Business to use this payment method.

caution

NuPay's accreditation process is still restricted to many kinds of businesses. If you're interested in using this payment method, please contact contato@malga.io

NuPay transaction Participants

• The receiver, Malga's client, which must possess an active NuPay for Business account.
• The payer, a buyer which must be a Nubank client.

NuPay payment flow

• To create a NuPay transaction you must use the NUPAY payment method upon the charge creation, set it's expiration date and send the documents which identify the buyer;
• A charge is registered directly in NuPay's system and a notification is sent to the payer's Nubank app;
• The payer must complete the payment straight through Nubank app;
• Upon payment confirmation, NuPay sends Malga a notification informing such payment was completed;
• Then the receiver Client will be notified that the charge was successfuly completed.

This process can be seen in the following diagram.

info

NuPay charges are asynchronous in nature, which means that on creating a new charge you will only receive a confirmation of it's creation, but not it's conclusion. The authorization or rejection of a charge will be notified through your webhooks.

Status change notification

object	event	description
transaction	pending	Event emitted when a charge is registered and the charge notification was sent to the payer
transaction	authorized	Event emitted when confirmation of payment of charge is acknowledged
transaction	failed	Event emitted when the charge is declined by NuPay before being created, with no financial chargeback
transaction	canceled	Event emitted when the charge is declined by NuPay before being authorized, with no financial chargeback
transaction	voided	Event emitted when the charge is canceled after being authorized, producing financial chargeback

Testing NuPay's paid charge notification

To test your webhook integration with Malga you can code it straight in your system or use a service such as request.bin or pipedream.com to initially validate the events you are receiving. All you need to do is to create a new endpoint in one of these services and register it in a Malga webhook. All events will be registered in these services so you can query them and debug you implementation.

In the sandbox environment, sandbox-api.malga.io we allow you to manually update previously created transactions status to authorized, voided and charged_back. This way you can create a transaction and simulate the desired event.

Request to manually update a NuPay charge as paid in sandbox

curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/<CHARGE_ID>' \
          --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
          --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "status": "authorized"
          }'

Charge example

Create a NuPay charge from the customer source using 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": "d5b792ba-4d76-46b4-a94d-c7ddae75cf9e",
    "orderId": "5556",
    "amount": 100,
    "currency": "BRL",
    "paymentMethod": {
        "paymentType": "nupay",
        "taxValue": 1,
        "delayToAutoCancel": 200,
        "orderUrl": "https://order.com.br",
        "returnUrl": "https://return-url.com.br",
        "cancelUrl": "https://cancel-url.com.br"
    },
    "paymentSource": {
        "sourceType": "customer",
        "customer": {
            "document": {
                "number": "36436702067",
                "type": "cpf"
            },
            "name": "Jose das Flores",
            "email": "jose@gmail.com",
            "phoneNumber": "11998324141",
            "address": {
                "street": "Rua 1",
                "streetNumber": "120",
                "zipCode": "01714140",
                "state": "SP",
                "city": "São Paulo"
            }
        }
    },
    "fraudAnalysis": {
        "customer": {
            "browser": {
                "ipAddress": "127.0.0.1"
            }
        },
        "cart": {
            "items": [
                {
                    "sku": "123",
                    "name": "desc",
                    "quantity": 1,
                    "unitPrice": 1,
                    "risk": "Low"
                }
            ]
        }
    }
}'

< HTTP/2 201
{
    "id": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1",
    "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d",
    "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176",
    "description": null,
    "orderId": "8222",
    "createdAt": "2022-09-30T21:33:42.955Z",
    "amount": 100,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": null,
    "status": "pending",
    "paymentMethod": {
        "paymentType": "nupay"
    },
    "paymentSource": {
        "sourceType": "customer",
        "customerId": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f"
    },
    "transactionRequests": [
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "NUPAY",
            "transactionId": "2c57caad-136d-4bc4-a265-c72d408d5ef8",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "pending",
            "responseTs": "1084ms",
            "nupay": {
                "expiresIn": 200
            }
        }
    ]
}

caution

It is mandatory to send the cart informations to create a NuPay transaction.

NuPay refund

NuPay's refund, just as charges, happens asynchronously. Once it is requested a refund process is initiated and will have it's finishing deadline set through the delayToCompose property, in days.

This happens because the clearing process on NuPay's side happens on a daily basis and it is necessary to use new credit generated from transactions to compose the necessary refund value. If you wish to learn more about this process, please check out NuPay's documentation on refunds.

NuPay's refund flow is represented in the following diagram.

NuPay's refund request example

When a refund request is made, it is received as a transaction with the refund_pending status which possesses a transactionRequest of the type void with processing status, informing that the refund is being processed.

curl --location --request POST 'https://api.malga.io/v1/charges/<CHARGE_ID>/void' \
--header 'X-Client-Id: <YOUR_CLIENT_ID>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 100,
    "delayToCompose": 100
}'

< HTTP/2 201
{
    "id": "4cbF2516-b8c0-4222-a28d-2c7e22a9ebe1",
    "clientId": "11111111-36dc-4654-9dba-e7167d0e5e2d",
    "merchantId": "7cCf07e8-9798-4bf6-a97e-7f0e0822c176",
    "description": null,
    "orderId": "8222",
    "createdAt": "2022-09-30T21:33:42.955Z",
    "amount": 100,
    "originalAmount": 100,
    "currency": "BRL",
    "statementDescriptor": null,
    "status": "refund_pending",
    "paymentMethod": {
        "paymentType": "nupay"
    },
    "paymentSource": {
        "sourceType": "customer",
        "customerId": "ae1b1f52-ee01-4014-9eb6-e529dd6d3f5f"
    },
    "transactionRequests": [
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "NUPAY",
            "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "processing",
            "requestType": "void",
            "responseTs": "1123ms",
            "nupay": {
                "refundId": "72cecc64-2079-4128-8cb0-c5a4ed8fa444"
            }
        },
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "NUPAY",
            "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": null,
            "nupay": {
                "installmentsNumber": 1,
                "paymentType": "spintest-link"
            }
        },
        {
            "id": "1c57caad-136d-4bc4-a265-c72d408d5ef7",
            "createdAt": "2022-09-30T21:33:42.969Z",
            "updatedAt": "2022-09-30T21:33:44.105Z",
            "idempotencyKey": "84d0ed42-0239-4618-b3b9-e31114bba17b",
            "providerId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "providerType": "NUPAY",
            "transactionId": "72cecc64-2079-4128-8cb0-c5a4ed8fa995",
            "amount": 100,
            "authorizationCode": null,
            "authorizationNsu": null,
            "requestStatus": "success",
            "requestType": "pending",
            "responseTs": "1084ms",
            "nupay": {
                "expiresIn": 200
            }
        }
    ]
}

Testing refund update

Upon creating a refund for a NuPay transaction in our sandbox, it is created with the refund_pending status. In order to test the refund update in the sandbox environment you must update it's status manually with a request, as described in the receiving notifications session.

Request to manually update a NuPay charge as voided in sandbox

curl --location --request POST 'https://sandbox-api.malga.io/v1/charges/<CHARGE_ID>' \
          --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
          --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "status": "voided"
          }'