Skip to content

PIX

PIX is a Brazilian payment method, officially launched by the local Central Bank, that enables immediate payment confirmation and 24/7 availability. The user can complete the payment using any Home Banking or Ewallet App, by copying and pasting a Transaction ID or scanning a QR code

HTTP Request

POST /v1/payments/charges/pix

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

create a PIX payment with DIRECT payment flow

Request Body
{
    "idempotencyKey": "hz-testpixdynamic-230703-001",
    "amount": 100,
    "currency": "USD",
    "country": "BR",
    "paymentMethod": "PIX_DYNAMIC_QR",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "email": "thiago@example.com",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "phone": "+55 5058149876",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "riskData": {
        "ipAddress": "192.0.0.130"
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+55 5058149876",  
            "email": "thiago@example.com",
            "address": {  
                "zipCode": "04849333",
                "state": "SP",
                "city": "sao paulo",
                "district": "Jardim Gaivotas",
                "street": "Rua 9 de setembro",
                "number": "15",
                "complement": "casa",
                "country": "BR"
            }
        }
    },
    "expirationInfo": {
        "expiresAt": 1688396709
    },
    "callbackUrl": "",
    "description": "hello world",
    "subMerchantId": "UUID"
}

create a PIX payment with REDIRECT payment flow

Request Body
{
    "idempotencyKey": "hz-testpixdynamic-230703-001",
    "amount": 100,
    "currency": "USD",
    "country": "BR",
    "paymentMethod": "PIX_DYNAMIC_QR",
    "paymentFlow": "REDIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "email": "thiago@example.com",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "phone": "+55 5058149876",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "riskData": {
        "ipAddress": "192.0.0.130"
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "+55 5058149876",  
            "email": "thiago@example.com",
            "address": {  
                "zipCode": "04849333",
                "state": "SP",
                "city": "sao paulo",
                "district": "Jardim Gaivotas",
                "street": "Rua 9 de setembro",
                "number": "15",
                "complement": "casa",
                "country": "BR"
            }
        }
    },
    "expirationInfo": {
        "expiresAt": 1688396709
    },
    "callbackUrl": "",
    "description": "hello world",
    "subMerchantId": "UUID",
    "merchantRedirectInfo": {
        "merchantPageUrl": "https://www.merchantpageexample.com/123456"
    }
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "idempotencyKey": "hz-testpixdynamic-230703-001",
    "referenceId": "hz-testpixdynamic-230703-001",
    "paymentFlow": "REDIRECT",
    "paymentMethod": "PIX_DYNAMIC_QR",
    "amount": 100,
    "currency": "USD",
    "finalAmount": 550,
    "finalCurrency": "BRL",
    "country": "BR",
    "createTime": "2023-07-03 09:32:32 UTC",
    "scheduledTime": "2023-07-03 09:59:46 UTC",
    "payer": {
        "name": "Thiago Gabriel",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "email": "thiago@example.com",
        "phone": "+55 81987654321",
        "billingAddress": {
            "br": true,
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "district": "Jardim Gaivotas",
            "city": "sao paulo",
            "state": "SP",
            "zipCode": "04849333",
            "country": "BR"
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "hello world",
    "callbackUrl": "",
    "transferDetails": {
        "pix": {
            "qrCode": "00020126890014BR.GOV.BCB.PIX2567api-pix.bancobs2.com.br/spi/v2/61ee4152-b3a2-435f-945f-ac52a268f2c552040000530398654045.505802BR5925LIQUIDO BRL PAGAMENTOS DI6014Belo Horizonte61083038040362070503***63045CE7",
            "qrCodeType": "DYNAMIC",
            "expirationTime": "2023-07-03 15:05:09 UTC"
        }
    },
    "amountDetails": {
        "taxAmountDetails": [
            {
                "taxRate": {
                    "modifierType": "RATE",
                    "rate": 0.0038,
                    "type": "BR_IOF_FX_TAX"
                },
                "amount": 2
            }
        ],
        "fxAmountDetails": {
            "fxRate": {
                "modifierType": "RATE",
                "base": "USD",
                "target": "BRL",
                "timestamp": 1664443743,
                "exchangeRate": 5.48350980
            },
            "baseAmount": 100,
            "targetAmount": 548
        }
    },
    "subMerchantId": "UUID",
    "redirectUrl": "https://www.redirect-qa.liquido.com?uid=97d6483b-78f5-43e6-8efc-5ef415b7a33f",
    "merchantRedirectInfo": {
        "merchantPageUrl": "https://www.merchantpageexample.com/123456"
    }
}

Notification / Callback

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data":  {
        "chargeDetails": {
            "transferStatusCode": 200,
            "idempotencyKey": "hz-testpixdynamic-230703-001",
            "referenceId": "hz-testpixdynamic-230703-001",
            "paymentFlow": "REDIRECT",
            "paymentMethod": "PIX_DYNAMIC_QR",
            "amount": 100,
            "currency": "USD",
            "finalAmount": 550,
            "finalCurrency": "BRL",
            "country": "BR",
            "createTime": "2023-07-03 09:32:32 UTC",
            "scheduledTime": "2023-07-03 09:59:46 UTC",
            "finalStatusTime": "2023-07-03 09:59:46 UTC",
            "payer": {
                "name": "Thiago Gabriel",
                "document": {
                    "documentId": "53033315550",
                    "type": "CPF"
                },
                "email": "thiago@example.com",
                "phone": "+55 81987654321",
                "billingAddress": {
                    "br": true,
                    "street": "Rua 9 de setembro",
                    "number": "15",
                    "complement": "casa",
                    "district": "Jardim Gaivotas",
                    "city": "sao paulo",
                    "state": "SP",
                    "zipCode": "04849333",
                    "country": "BR"
                }
            },
            "transferStatus": "IN_PROGRESS",
            "description": "hello world",
            "callbackUrl": "",
            "transferDetails": {
                "pix": {
                    "qrCode": "00020126890014BR.GOV.BCB.PIX2567api-pix.bancobs2.com.br/spi/v2/61ee4152-b3a2-435f-945f-ac52a268f2c552040000530398654045.505802BR5925LIQUIDO BRL PAGAMENTOS DI6014Belo Horizonte61083038040362070503***63045CE7",
                    "qrCodeType": "DYNAMIC",
                    "expirationTime": "2023-07-03 15:05:09 UTC"
                }
            },
            "amountDetails": {
                "taxAmountDetails": [
                    {
                        "taxRate": {
                            "modifierType": "RATE",
                            "rate": 0.0038,
                            "type": "BR_IOF_FX_TAX"
                        },
                        "amount": 2
                    }
                ],
                "fxAmountDetails": {
                    "fxRate": {
                        "modifierType": "RATE",
                        "base": "USD",
                        "target": "BRL",
                        "timestamp": 1664443743,
                        "exchangeRate": 5.48350980
                    },
                    "baseAmount": 100,
                    "targetAmount": 548
                }
            },
            "subMerchantId": "UUID",
            "redirectUrl": "https://www.redirect-qa.liquido.com?uid=97d6483b-78f5-43e6-8efc-5ef415b7a33f",
            "merchantRedirectInfo": {
                "merchantPageUrl": "https://www.merchantpageexample.com/123456"
            }
        }
    }
}

HTTP Headers Details

Key Value
Authorization "bearer" + " " + {{access_token}}
x-api-key {{api_key}}

Request Body Parameters

Parameter Required Type Description
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system.
amount Long The transfer amount. The minimum settlement granularity of the current currency, such as 100=1BRL
country String country code
currency String The currency code of the transferred fund
paymentMethod String payment method, enum value as PIX_DYNAMIC_QR
paymentFlow String payment flow, enum value as DIRECT or REDIRECT
payer JSON payer info
expirationInfo JSON pix payment expiration info. The number of seconds to increment must be between 3600 and 604800. If you want to activate a long-term valid PIX QR code, please contact our sales manager
orderInfo JSON order info
riskData JSON risk control info
description String description of payment.
NOTE:
1. The max length accepted is 25 characters.
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
subMerchantId String The sub merchant ID. Required for PSPs.
merchantRedirectInfo JSON The merchant redirect info.

Payer Object Parameters

Parameter Required Type Description
name String fullname(Input specification: Only a combination of uppercase and lowercase letters, numbers and spaces is allowed. Spanish and Portuguese letters, and other special characters are not allowed).
email String email.
phone String Mobile Phone number.
document JSON Wallet holder identity proof, such as CPF for Brazil.
billingAddress JSON Billing address info.

document Object Parameters

Parameter Required Type Description
documentId String identity number
type String enum of CPF or CNPJ

billingAddress Object Parameters

Parameter Required Type Description
zipCode String zip code. such as CEP in Brazil
state String state. should be abbreviation, such as SP in Brazil
city String city name.
district String district name.
street String street name.
number String street number.
complement String complement info.
country String country code.

orderInfo Object Parameters

Parameter Required Type Description
orderId String order identity number
shippingInfo JSON shipping info

shippingInfo Object Parameters

Parameter Required Type Description
name String shipping name
phone String Mobile phone number. Should include “+55” as a prefix.
email String email address
address JSON the same as billingAddress

RiskData Object Parameters

Parameter Required Type Description
ipAddress String Payer's IP address

expirationInfo Object Parameters

Parameter Required Type Description
expiresAt Long QR code will expire at that time. unix timestamp in seconds. EX: 1651035000. The number of seconds to increment must be between 3600 and 604800.

merchantRedirectInfo Object Parameters

Parameter Required Type Description
merchantPageUrl String It is a URL that redirects to merchant page. It should be include when you need Liquido to redirect your customers back to your page after customers finish payments.
This URL can only be set when ‘paymentFlow’ is ‘REDIRECT’ in the payment request.

Response Body Details

Parameter Required Type Description
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system
referenceId String Unique key to payment ticket
amount Long The transfer amount. The minimum settlement granularity of the current currency, such as 100=1BRL
country String country code
currency String The currency code of the transferred fund
finalAmount String The final amount that is used for creating the charge order. EX: for charge orders with FX conversion, this field represents the converted amount from the original requested amount.
finalCurrency String The currency code of the finalAmount.
paymentMethod String payment flow, enum value as PIX_DYNAMIC_QR
payer JSON payer info
transferDetails JSON transaction details info
description String description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
createTime String Payment ticket created time
scheduledTime String Payment ticket scheduled time
finalStatusTime String Transfer final status update time, final status include SETTLED, FAILED
transferStatus String Transfer status, SETTLED, IN_PROGRESS, FAILED
transferStatusCode int Transfer status code, 200 transaction SETTLED or IN_PROGRESS, other FAILED
transferErrorMsg String Transfer error message if failed
amountDetails JSON Amount details info
subMerchantId String The sub merchant ID.
redirectUrl String The URL where you must redirect your customer to complete the payment. It will be included in the response when “paymentFlow” is “REDIRECT” in the request parameters.
merchantRedirectInfo JSON The merchant redirect info.

transferDetails Object Parameters

Parameter Type Description
pix JSON pix detail info

pix Object Parameters

Parameter Type Description
qrCode String barcode of pix order
qrCodeType String enum value of DYNAMIC
expirationTime String expired time

AmountDetails

Parameter Type Description
taxAmountDetails JSON Tax amount details info
fxAmountDetails JSON FX amount details info

TaxAmountDetails

Parameter Type Description
taxRate JSON Tax rate info
amount Long Tax amount for this payment

TaxRate

Parameter Type Description
type String Taxes type string
rate Double Tax rate for this payment

FXAmountDetails

Parameter Type Description
fxRate JSON FX rate info
baseAmount Long The amount before exchange
targetAmount Long The amount after exchange

FXRate

Parameter Type Description
timestamp Long The time for getting exchange rate
base String Source currency
target String Target currency
exchangeRate Double The actual exchange rate

Transfer Status

Parameter Description
IN_PROGRESS The transaction of this method has started, but no transactions have been processed yet.
SETTLED The funds of the transaction of this payment have been transferred to the store.
REFUNDING The transaction of this payment is refunding.
REFUNDED The transaction of this payment method has been refunded.
CANCELLED The transaction of this payment has been cancelled.
FAILED There was an error while processing the transaction of this payment. This status is followed by a message with more details about the error.

Notification Event Type

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;
Back to top