Skip to content

Pix

Info

Pix transactions support only Brazilian reals (BRL).

This alternative payment method supports the following operations:

Payment

Payment flow

  1. The customer selects Pix as a payment method.
  2. The merchant sends a payment request to PaySage.io.
  3. PaySage.io returns a response containing a QR code and a hash.
  4. The merchant displays the QR code and the hash to the customer.
  5. The customer scans the QR code in their bank application and complete the payment.
  6. Alternatively, the customer can copy the hash and insert it in their mobile application and complete the payment.
  7. PaySage.io sends a webhook notification to the merchant.
  8. The merchant sends a response to the webhook notification.
Request

Send a payment request with the following additional parameters:

Parameter Type Description
request object
expired_at string A date and time until QR code and hash are valid, in the ISO-8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example 2019), MM – month (for example 02), DD – day (for example 09), hh – hours (for example 18), mm – minutes (for example 20), ss – seconds (for example 45), TZD – time zone (+hh:mm or –hh:mm). If not specified, the QR code will be valid for 24 hours.
customer object A section of the customer details.
first_name * required
 string The customer's first name.
last_name * required
 string The customer's last name.
taxpayer_id * required
 string Taxpayer number (CPF or CNPJ number).
email * required
 string The customer's email address.
method object A section of the payment method information.
type * required
 string pix
Request example 
{
    "request":{
        "amount":100,
        "currency":"BRL",
        "description":"description",
        "test": false,
        "expired_at": "2023-11-01T15:00:00+01:00",
        "return_url":"https://merchant.ltd/return",
        "customer":{
            "first_name":"John",
            "last_name":"Doe",
            "email": "example@example.com",
            "taxpayer_id": "390.533.447-05"
        },
        "method":{
            "type": "pix"
        }
    }
}
Response

The response will additionally contain the pix object with qr_code and hash parameters.

Parameter Type Description
pix object
qr_code string QR-code for the payment, Base64 encoded.
hash string Code that the customer inserts in their banking application to complete the payment.
Successful response example 
{
    "transaction": {
        "uid": "36b89d1b-2eef-4202-b99f-0f5842b2665a",
        "type": "payment",
        "status": "pending",
        "amount": 100,
        "currency": "BRL",
        "description": "description",
        "created_at": "2023-10-23T11:49:18Z",
        "updated_at": "2023-10-23T11:49:20Z",
        "method_type": "pix",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/36b89d1b-2eef-4202-b99f-0f5842b2665a/2cbb1fe89ed4f965a88d753c2ebf92d315058880b38c8ec2004255fbe099f140?language=en",
        "payment": {
            "status": "pending",
            "gateway_id": 3333,
            "message": "Transaction was initialized"
        },
        "pix": {
            "qr_code": "PHN2ZyBoZWlnaHQ9IjUxMSIPSI3IiB4PS...",
            "hash": "00020101021126860014br.gov.bcb.pix013601898bcc-516d-2480-6bd1-49ad4b4ba3880224018b5c5e-32a9-a1b1-b67a-52040000530398654031.05802BR5921PSP - Cash Out6002BR61080000000062070503***6304E6CA"
        },
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "example@example.com",
            "taxpayer_id": "390.533.447-05",
            "ip": null
        },
        "manually_corrected_at": null,
        "message": "Transaction was initialized",
        "test": false,
        "language": "en",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "example@example.com",
            "taxpayer_id": "390.533.447-05"
        },
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },
        "gateway": {
            "iframe": false
        }
    }
}

Payout

Request

Send a payout request with the following data:

Parameter Type Description
method object A section of the payout method.
type * required
 string pix
account_number * required
 string Identifier of the bank account, to which the payout is made.
Request example 
{
    "request":{
        "amount":100,
        "currency":"BRL",
        "description":"description",
        "test": true,
        "return_url":"https://your-success.url",
        "method":{
            "type": "pix",
            "account_number": "33281283609809"
        }
    }
}
Response
Successful response example 
{
    "transaction": {
        "uid": "73139810-53fd-4a66-90d0-44bd42d7aae7",
        "type": "payout",
        "status": "pending",
        "amount": 100,
        "currency": "BRL",
        "description": "description",
        "created_at": "2023-10-23T13:36:57Z",
        "updated_at": "2023-10-23T13:36:59Z",
        "manually_corrected_at": null,
        "method_type": "pix",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/73139810-53fd-4a66-90d0-44bd42d7aae7/3901a763d93ae4d7345e636a7887498e399d03e6050e0e54601cfb8f2dc4706f",
        "payout": {
            "status": "pending",
            "gateway_id": 3333,
            "ref_id": "018b5cc0-c6b1-fa0b-1c88-41836d5219bc",
            "message": "Transaction was initialized"
        },
        "pix": {
            "type": "pix",
            "account_number": "33281283609809"
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "message": "Transaction was initialized",
        "test": true,
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        }              
    }
}

Refund

Request

Send a standard refund request. The amount value must not exceed the amount of the parent transaction.