Skip to content

Utility Payment

Utility payment

Register a payment

Register a payment for the bills of life services

HTTP Request

POST /v1/marketplace/sales/utility

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "280a03fc-2255-11eb-adc1-0242ac120002",
    "merchantName":"CFE",
    "referenceNumber":"972101002847",
    "amount":123,
    "countryCode":"MX",
    "currency": "MXN",
    "paymentType":"PAY_WITH_LINK",
    "allowPaymentMethods": [
        "BANK_TRANSFER_MX",
        "CREDIT_CARD"
    ],
    "targetPhoneNumber": "+5511999999999",
    "email": "liquido-test@gmail.com",
    "billingAddress": {
        "zipCode": "04849333",
        "state": "SP",
        "city": "sao paulo",
        "district": "Jardim Gaivotas",
        "street": "Rua 9 de setembro",
        "number": "15",
        "complement": "casa",
        "country": "MX"
    },
    "callbackUrl": "https://your-domain/callback/",
    "redirectUrl": "https://your-domain/checkout-page"
}
Content-Type: application/json
{
    "statusCode": 200,
    "errorMsg": "",
    "idempotencyKey": "7e18e719-0000-0716-a92a-2b4faeb70008",
    "transactionId": "20210715-175206-145-0369-0449",
    "transactionStatus": "IN_PROGRESS",
    "transactionStatusCode": 200,
    "transactionErrorMsg": ""
}

HTTP Headers Parameters

Key Value
Content-Type application/json
x-api-key {{api_key}}

Request Body Parameters

Parameter Required Type Description
idempotencyKey String Unique key to ensure idempotent requests, no longer than 128 bits
merchantName String Merchant name
referenceNumber String Reference number of the bill
amount int Amount
countryCode String Country abbreviation, following ISO 3166-1 alpha-2 code standard, 2 bits, eg. BR, MX
currency String Currency type, eg MXN for Mexico
paymentType String Payment type, enumeration value: PREPAID, PAY_WITH_LINK, do not fill in the default PREPAID
allowPaymentMethods String Declare which payment methods are included in the payment page. The default value is CREDIT_CARD. (Only when the payment type is PAY_WITH_LINK may need to be filled in)
targetPhoneNumber String Mobile phone number (only if the payment type is PAY_WITH_LINK)
email String Email (only if the payment type is PAY_WITH_LINK)
billingAddress String Billing address. If the merchant pre-collected the user's billing address before the payment process, it can send it to liquido when creating the payment link. This information can be used to pre-fill the Boleto payment form. (Only when the payment type is PAY_WITH_LINK may need to be filled in)
callbackUrl String When the payment status changes, liquido will send a post request to the callbackUrl.
redirectUrl String When the redirectUrl is not empty, the payment link will be redirected to the redirectUrl after successful payment. (Only when the payment type is PAY_WITH_LINK may need to be filled in)

AllowPaymentMethods Object Parameters

Payment Method Country Limit
CREDIT_CARD BR, MX, CO
PIX BR
BOLETO BR > 500BRL
BANK_TRANSFER_BR BR
BANK_TRANSFER_MX MX
PAY_CASH MX, CO
PSE CO >1500COP
NEQUI CO >1500COP

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.

Response Body Details

Parameter Type Description
statusCode int Status code, 200 success, 401 access denied, 422 parameter error, 500 internal error
errorMsg String If transaction failed, return error message
idempotencyKey String Unique key to ensure idempotent requests
transactionId String Transaction ID, sometime will be empty when processing
transactionStatus String Transaction status, enumeration as SETTLED, IN_PROGRESS or FAILED
transactionStatusCode int Transaction status code, 200 success or processing, other meaning transaction failed
transactionErrorMsg String Error message of the failed transaction

Check Transfer Status

Check the status of the bill payment by idempotencyKey.

HTTP Request

GET /v1/marketplace/sales/utility/key/{{idempotencyKey}}

Request Headers
{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

Response

Content-Type: application/json
{
    "statusCode": 200,
    "errorMsg": "",
    "idempotencyKey":"280a03fc-2255-11eb-adc1-0242ac120001",
    "transactionId":"09461d96-2252-11eb-adc1-0242ac120002",
    "transactionStatus":"SETTLED",
    "transactionStatusCode": 200,
    "transactionErrorMsg": "",
    "merchantName": "CFE",
    "price": "10",
    "priceInCents": "1000",
    "currency": "MXN",
    "createTime": "2021-07-26T20:41:53",
    "finalStatusTime": "2021-07-26 12:41:53 GMT+00:00",
    "referenceNumber": "972101002847"
}

HTTP Headers Details

Key Value
x-api-key {{api_key}}
Content-Type application/json

PATH and Query Parameters

Parameter Required Type Description
idempotencyKey String Unique key to ensure idempotent requests

Response Body Details

Parameter Type Description
statusCode int Status code, 200 success, 401 access denied, 422 parameter error, 500 internal error
errorMsg String If transaction failed, return error message
idempotencyKey String Unique key to ensure idempotent requests
transactionId String Transaction ID, sometime will be empty when processing
transactionStatus String Transaction status, enumeration as SETTLED, IN_PROGRESS or FAILED
transactionStatusCode int Transaction status code, 200 success or processing, other meaning transaction failed
transactionErrorMsg String Error message of the failed transaction
merchantName String Merchant name
price String Utility services amount
priceInCents Long Gift card amount.The minimum settlement granularity of the current currency, such as 100=1BRL
currency String Utility services currency type, eg BRL for Brazil
createTime Time Utility services purchase request creation time
finalStatusTime Time Utility services purchase request completed time
referenceNumber String Reference number of the bill

Query Providers

Get available utility services providers.

HTTP Request

GET /v1/marketplace/sales/utility/{{countryCode}}/merchants

Request Headers
{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

Response

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "merchants": [
        {
            "merchantId": "166",
            "merchantName": "CFE",
            "iconUrl": "https://gestopago.portalventas.net/sistema/images/gestopago/servicios/166.png",
            "description": "Pago de Servicios (Energía)"
        },
        {
            "merchantId": "756",
            "merchantName": "ENGIE MAXIGAS",
            "iconUrl": "https://gestopago.portalventas.net/sistema/images/gestopago/servicios/756.png",
            "description": "Pago de Servicios (Energía)"
        }
    ]
}

HTTP Headers Details

Key Value
x-api-key {{api_key}}
Content-Type application/json

PATH and Query Parameters

Parameter Type Description
countryCode String Country abbreviation, following ISO 3166-1 alpha-2 code standard, 2 bits, eg BR, MX

Response Body Details

Parameter Type Description
statusCode int Status code, 200 success, 401 access denied, 422 parameter error, 500 internal error
errorMsg String Error message if failed
merchants JSON Array List of utility services provider
merchantId String Merchant ID
merchantName String Merchant name
iconUrl String Merchant icon URL
description String Merchant description
Back to top