Gift Cards
Purchase Gift Cards
HTTP Request
POST
/v1/marketplace/sales/gift_cards
Request Response
Request Headers {
"Content-Type" : "application/json" ,
"Authorization" : "Bearer {{access_token}}" ,
"x-api-key" : "{{api_key}}"
}
Request Body {
"idempotencyKey" : "280a03fc-2255-11eb-adc1-0242ac120002" ,
"sku" : "NETFLI300" ,
"currency" : "MXN" ,
"countryCode" : "MX" ,
"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" : "280a03fc-2255-11eb-adc1-0242ac120002" ,
"transactionId" : "20200721-184332-824-3257-1404" ,
"transactionStatus" : "IN_PROGRESS" ,
"transactionStatusCode" : 200 ,
"transactionErrorMsg" : ""
}
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
sku
String
gift card SKU
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, 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
>= 5BRL
BANK_TRANSFER_BR
BR
BANK_TRANSFER_MX
MX
PAY_CASH
MX, CO
<= 20,000 MXN or <= 3,000,000 COP
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 Order Status
Check for gift card order status
HTTP Request
GET
/v1/marketplace/sales/gift_cards/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" : "NETFLI300" ,
"price" : "300" ,
"priceInCents" : "30000" ,
"currency" : "MXN" ,
"createTime" : "2021-07-26T20:41:53" ,
"finalStatusTime" : "2021-07-26 12:41:53 GMT+00:00" ,
"activationCode" : "AAABBNDS111EBEM" ,
"activationMessage" : "Activation Message"
}
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
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
sku
String
Gift card SKU
price
String
Gift card amount
priceInCents
Long
Gift card amount.The minimum settlement granularity of the current currency, such as 100=1BRL
currency
String
Gift card currency type, eg BRL for Brazil
createTime
Time
Gift card purchase request creation time
finalStatusTime
Time
Gift card purchase request completed time
activationCode
String
Gift card activation code
activationMessage
String
Gift card activation message
Gift Cards Providers
Check for available gift card providers of the designated country.
HTTP Request
GET
/v1/marketplace/sales/gift_cards/{{countryCode}}/merchants
Request Headers {
"Authorization" : "Bearer {{access_token}}" ,
"x-api-key" : "{{api_key}}"
}
Response
Content-Type: application/json {
"statusCode" : 200 ,
"errorMsg" : "" ,
"merchants" : [
{
"merchantId" : "Netflix" ,
"merchantName" : "Netflix" ,
"iconUrl" : "https://aws.s3.some.url/netflix.jpeg" ,
"description" : null
},
{
"merchantId" : "Spotify" ,
"merchantName" : "Spotify" ,
"iconUrl" : "https://aws.s3.some.url/Spotify.jpeg" ,
"description" : null
},
......
]
}
Key
Value
Content-Type
application/json
x-api-key
{{api_key}}
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 gift card provider
merchantId
String
Merchant ID
merchantName
String
Merchant name
iconUrl
String
Merchant icon URL
description
String
Merchant description
Gift Cards Skus List
Get available gift cards skus of the designated country
HTTP Request
GET
/v1/marketplace/sales/gift_cards/{{countryCode}}/skus
Request Headers {
"Authorization" : "Bearer {{access_token}}" ,
"x-api-key" : "{{api_key}}"
}
Response
Content-Type: application/json {
"statusCode" : 200 ,
"errorMsg" : "" ,
"skus" : [
{
"sku" : "NETFLI150" ,
"price" : "150" ,
"currency" : "MXN" ,
"merchantId" : "Netflix" ,
"description" : "Netflix 150"
},
{
"sku" : "NETFLI300" ,
"price" : "300" ,
"currency" : "MXN" ,
"merchantId" : "Netflix" ,
"description" : "Netflix 300"
},
......
]
}
Key
Value
Content-Type
application/json
x-api-key
{{api_key}}
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
Skus list
sku Object Details
Parameter
Type
Description
name
String
Gift card package name
description
String
Gift card package description
price
String
Gift card package price. The minimum settlement granularity of the current currency, such as 100=1BRL
currency
String
Gift card currency type
merchantId
String
Gift card merchant ID
Get gift card skus of designated merchant
HTTP Request
GET
/v1/marketplace/sales/gift_cards/{{countryCode}}/{{merchantId}}/skus
Request Headers {
"Authorization" : "Bearer {{access_token}}" ,
"x-api-key" : "{{api_key}}"
}
Response
Content-Type: application/json {
"statusCode" : 200 ,
"errorMsg" : "" ,
"skus" : [
{
"sku" : "NETFLI150" ,
"price" : "150" ,
"currency" : "MXN" ,
"merchantId" : "Netflix" ,
"description" : "Netflix 150"
},
{
"sku" : "NETFLI300" ,
"price" : "300" ,
"currency" : "MXN" ,
"merchantId" : "Netflix" ,
"description" : "Netflix 300"
},
......
]
}
Key
Value
Content-Type
application/json
x-api-key
{{api_key}}
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
Gift card merchant 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
Skus list
sku Object Details
Parameter
Type
Description
name
String
Gift card package name
description
String
Gift card package description
price
String
Gift card package price. The minimum settlement granularity of the current currency, such as 100=1BRL
currency
String
Gift card currency type
merchantId
String
Gift card merchant ID