Mobile Phone Top Up

Perform mobile top up

Submit Top Up

HTTP Request

POST /sales/topups

Request Headers

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

Request Body

{
    "idempotencyKey": "280a03fc-2255-11eb-adc1-0242ac120002",
    "targetPhoneNumber": "551234567890",
    "sku": "TAE010",
    "currency": "MXN",
    "countryCode": "MX",
    "paymentType":"PAY_WITH_LINK",
    "allowPaymentMethods": [
        "BANK_TRANSFER_MX",
        "CREDIT_CARD"
    ],
    "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"
}

Response

Content-Type: application/json

{
    "statusCode": 200,
    "errorMsg": "",
    "idempotencyKey": "7e18e719-0000-0716-a92a-2b4faeb70008",
    "transactionId": "20210715-175206-145-0369-0449",
    "transactionStatus": "SETTLED",
    "transactionStatusCode": 200,
    "transactionErrorMsg": ""
}

HTTP Headers Details

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

JSON Body Parameters

Parameter	Type	Description
idempotencyKey	String	Unique key to ensure idempotent requests, no longer than 128 bits
targetPhoneNumber	String	Mobile Phone number
sku	String	The SKU of top up package
currency	String	Monetary unit, 3 bytes in length, such as BRL, MXN
countryCode	String	Country code, 2 bytes in length, such as BR, MX, without default MX
paymentType	String	Payment type, enumeration value: PREPAID, COUPON_CODE、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)
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	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 transaction SETTLED or IN_PROGRESS, other FAILED or REJECTED
transactionErrorMsg	String	Error message of the failed transaction

Check Top Up Status

Check top up status by idempotency key.

HTTP Request

GET /sales/topups/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": "",
    "sku": "TAE010",
    "price": "10",
    "priceInCents": "1000",
    "currency": "MXN",
    "createTime": "{{GIFTCARD_CREATE_TIME}}",
    "finalStatusTime": "{{GIFTCARD_FINAL_STATUS_TIME}}",
    "phoneNumber": "5581124237"
}

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	API status code, 200 success, 401 access denied, 422 parameter error, 500 internal error
errorMsg	String	If API requests failed, return error message
idempotencyKey	String	Unique key to ensure idempotent requests
transactionId	String	Transation ID, sometime will be empty when processing
transactionStatus	String	Transation status, SETTLED, FAILED, IN_PROGRESS
transactionStatusCode	int	Transaction status code, 200 transaction SETTLED or others error code
transactionErrorMsg	String	Transaction error message if failed
sku	String	Top up package SKU
price	String	Top up package amount
priceInCents	Long	Top up package amount.The minimum settlement granularity of the current currency, such as 100=1BRL
currency	String	Currency type, eg. BRL for Brazil
createTime	Time	The creation time of top up transaction
finalStatusTime	Timev The settled or failed time of top up transaction
phoneNumber	Time	Mobile phone number

Mobile Carriers

Return supported mobile carriers of current country

HTTP Request

GET /sales/topups/{{countryCode}}/merchants

Request Headers

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

Response

Content-Type: application/json

{
    "statusCode":200,
    "errorMsg": "",
    "merchants": [
        {
            "merchantId": "TA",
            "merchantName": "Telcel",
            "iconUrl": "https://s3.some.url/Telcel.jpeg",
            "description": "Telcel Tiempo Aire"
        },
        {
            "operatorId": "MOV",
            "operatorName": "Movistar",
            "iconUrl": "https://s3.some.url/Movistar.jpeg",
            "description": "Movistar Tiempo Aire"
        }
    ]
}

HTTP Headers Details

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

PATH and Query Parameters

Parameter	Required	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 available mobile carriers
merchantId	String	Carrier merchant ID
merchantName	String	Carrier name
iconUrl	String	Carrier icon URL
description	String	Carrier description

Get Top Up Packages

Get the list of top up package skus

HTTP Request

GET /sales/topups/{{countryCode}}}/skus

Request Headers

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

Response

Content-Type: application/json

{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "name": "UNE020",
            "description": "Unefon Tiempo Aire 015",
            "price": "20",
            "currency": "MXN",
            "merchantId": "Unefon"
        },
        {
            "name": "UNE020",
            "description": "Unefon Tiempo Aire 020",
            "price": "20",
            "currency": "MXN",
            "merchantId": "Unefon"
        }
    ]
}

HTTP Headers Details

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

PATH and Query Parameters

Parameter	Required	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
skus	JSON Array	Top up package list
name	String	Top up package SKU name
description	String	Top up Package description
price	String	Price of package. The minimum settlement granularity of the current currency, such as 100=1BRL
currency	String	Currency type
merchantId	String	Mobile carrier merchant ID

Get all recharge packages of designated mobile carriers

HTTP Request

GET /sales/topups/{{countryCode}}}/{{merchantId}}}/skus

Request Headers

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

Response

Content-Type: application/json

{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "name": "UNE050",
            "description": "Unefon Tiempo Aire 050",
            "price": "50",
            "currency": "MXN",
            "merchantId": "Unefon"
        },
        {
            "name": "UNE070",
            "description": "Unefon Tiempo Aire 070",
            "price": "70",
            "currency": "MXN",
            "merchantId": "Unefon"
        }
    ]
}

HTTP Headers Details

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

PATH and Query Parameters

Parameter	Required	Type	Description
countryCode		String	Country abbreviation, following ISO 3166-1 alpha-2 code standard, 2 bits, eg. BR, MX
merchantId		String	recharge mobile carrier ID

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
skus	JSON Array	Top up package list
name	String	Top up package SKU name
description	String	Top up Package description
price	String	Price of package. The minimum settlement granularity of the current currency, such as 100=1BRL
currency	String	Currency type
merchantId	String	Mobile carrier merchant ID