Create A Payment

Create A Credit Card Payment

When the user pays with a credit card for the first time, user needs to bring the credit card information in the request. The response will return a card id. When paying with the same card in the future, user can use the card id to initiate a request.

HTTP Request

POST /v1/payments/charges/card

Request Headers

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

create a card payment with card info

Request Body



id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1">{ "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0", "amount": 100, "currency": "MXN", "country": "MX", "paymentMethod": "CREDIT_CARD", "paymentFlow": "DIRECT", "payer": { "name": "username", "email": "username@liquido.com", "phone": "5512345678", "billingAddress": {   "zipCode": "03400", "state": "CDMX", "city": "Álamos", "street": "Simón Bolívar", "number": "12121" } }, "card": { "cardHolderName": "card_holder_name", "cardNumber": "4242424242424242", "expirationMonth": 06, "expirationYear": 2029, "cvc": "123" }, "orderInfo": {   "orderId": "test-order-id",   "shippingInfo": {  "name": "shipping test name",   "phone": "shipping phone",   "email": "thiago@example.com", "address": {  "street": "street name", "number": "building number", "complement": "unit, apt, etc.", "district": "district, neighborhood, etc.", "city": "city name", "state": "state, state code", "zipCode": "zip code, postal code", "country": "MX" } } }, "riskData": { "ipAddress": "192.168.0.1", "customProperties": {  "property1": "value1" } }, "description": "this is a test pay", "callbackUrl": "https://api.client.com/callback/" class="w">
create a card payment with card id
Request Body{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 100,
    "currency": "MXN",
    "country": "MX",
    "paymentMethod": "CREDIT_CARD",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "phone": "5512345678",
        "billingAddress": {  
            "zipCode": "03400",
            "state": "CDMX",
            "city": "Álamos",
            "street": "Simón Bolívar",
            "number": "12121"
        }
    },
    "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237",
    "riskData": {
        "ipAddress": "192.168.0.1",
        "customProperties": { 
            "property1": "value1"
        }
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/"
}

Response
Content-Type: application/json{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 100,
    "currency": "MXN",
    "country": "MX",
    "finalAmount": 100,
    "finalCurrency": "MXN",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "phone": "5512345678",
        "billingAddress": {  
            "zipCode": "03400",
            "state": "CDMX",
            "city": "Álamos",
            "street": "Simón Bolívar",
            "number": "12121"
        }
    },
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 06,
                "expirationYear": 2029,
                "bin": "424242",
                "last4": "4242",
                "brand": "VISA"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/"
}

Notification / Callback
Content-Type: application/json{
    "eventType": "CHARGE_SUCCEEDED",
        "data":  {
            "chargeDetails": {
                "transferStatusCode": 200,
                "transferErrorMsg": null,
                "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
                "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
                "paymentMethod": "CREDIT_CARD",
                "amount": 100,
                "currency": "MXN",
                "country": "MX",
                "finalAmount": 100,
                "finalCurrency": "MXN",
                "createTime": "2022-03-01 17:53:18 GMT-08:00",
                "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
                "finalStatusTime": null,
                "payer": {
                    "name": "username",
                    "email": "username@liquido.com",
                    "phone": "5512345678",
                    "billingAddress": {  
                        "zipCode": "03400",
                        "state": "CDMX",
                        "city": "Álamos",
                        "street": "Simón Bolívar",
                        "number": "12121"
                    }
                },
            "transferStatus": "SETTLED",
            "transferDetails": {
                "card": {
                    "cardInfo": {
                        "cardHolderName": "card_holder_name",
                        "expirationMonth": 06,
                        "expirationYear": 2029,
                        "bin": "424242",
                        "last4": "4242",
                        "brand": "VISA"
                    },
                    "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
                }
            },
            "description": "this is a test pay",
            "callbackUrl": "https://api.client.com/callback/"
        }
    }
}

Request Headers Parameters



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=1MXN


country

String
country code


currency

String
The currency code of the transferred fund


paymentMethod

String
payment method, enum value as CREDIT_CARD


paymentFlow

String
payment flow, enum value as DIRECT or REDIRECT


payer

JSON
payer info


card

JSON
credit card info. required if card id is empty.


cardId

String
card id. required if card info is empty.


capture

Boolean
set to false to create an authorization


installments

Integer
number of installments


orderInfo

JSON
order info


riskData

JSON
risk control 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.



Create A Credit Card Payment With Card Id
Please see here for further details.
Create A Credit Card Authorization
Please see here for further details.
Create A Credit Card Payment With Installments
Please see here for further details.
Create A Credit Card Redirect Payment
Please see here for further details.

Payer Object Parameters



Parameter
Required
Type
Description




name

String
fullname.


email

String
email. 
(email, phone, at least one of them is required)


phone

String
Mobile Phone number. 
(email, phone, at least one of them is required)


billingAddress

JSON
Billing address info.



BillingAddress Object Parameters



Parameter
Required
Type
Description




zipCode

String
zip code.


state

String
state.


city

String
city name.


street

String
street name.


number

String
street number.



OrderInfo Object Parameters



Parameter
Required
Type
Description




orderId

String
order identity number 
(Required only when object is provided)


shippingInfo

JSON
shipping info



ShippingInfo Object Parameters



Parameter
Required
Type
Description




name

String
shipping name


phone

String
phone number


email

String
email address


address

JSON
the same as billingAddress



Card Object Parameters



Parameter
Required
Type
Description




cardHolderName

String
Cardholder's full name.


cardNumber

String
16 digit number of the card, as a string without any separators.


expirationMonth

Integer
2 digit number representing the card's expiration month.


expirationYear

Integer
4 digit number representing the card's expiration year.


cvc

String
Credit card verification code.



RiskData Object Parameters



Parameter
Required
Type
Description




ipAddress

String
Payer's IP address


customProperties

JSON
Key/value pairs used to store additional custom metadata



Response Body Parameters



Parameter
Type
Description




transferStatus
String
Transfer status, SETTLED, IN_PROGRESS, AUTHORIZED, FAILED


transferStatusCode
int
Transfer status code, 200 transaction SETTLED, IN_PROGRESS or AUTHORIZED, other FAILED


transferErrorMsg
String
Transfer error message if failed


referenceId
String
Unique key to payment ticket, generated by Liquido.


idempotencyKey
String
Unique key to ensure idempotent requests. given by the merchant in their system


amount
Long
The transfer amount


country
String
country code


currency
String
The currency code of the transferred fund


finalAmount
Long
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 method, enum value as CREDIT_CARD, PIX_STATIC_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



TransferDetails Object Parameters



Parameter
Type
Description




card
JSON
card detail info



Card Object in TransferDetails Parameters



Parameter
Type
Description




cardInfo
JSON
card detail info


cardId
String
card id, can use it to create a card payment instead of card info


installments
Integer
number of installments



CardInfo Object in response Parameters



Parameter
Type
Description




cardHolderName
String
Cardholder's full name.


bin
String
first 6 digit number of the card


last4
String
last 4 digit number of the card


brand
String
Credit card brand. such as Visa, Mastercard


expirationMonth
Integer
2 digit number representing the card's expiration month.


expirationYear
Integer
4 digit number representing the card's expiration year.



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.


CHARGED_BACK
The transaction of this payment has been reported as chargeback.


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;

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

Parameter	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=1MXN
country	String	country code
currency	String	The currency code of the transferred fund
paymentMethod	String	payment method, enum value as CREDIT_CARD
paymentFlow	String	payment flow, enum value as DIRECT or REDIRECT
payer	JSON	payer info
card	JSON	credit card info. required if card id is empty.
cardId	String	card id. required if card info is empty.
capture	Boolean	set to false to create an authorization
installments	Integer	number of installments
orderInfo	JSON	order info
riskData	JSON	risk control 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.

Parameter	Type	Description
name	String	fullname.
email	String	email. (email, phone, at least one of them is required)
phone	String	Mobile Phone number. (email, phone, at least one of them is required)
billingAddress	JSON	Billing address info.

Parameter	Type	Description
zipCode	String	zip code.
state	String	state.
city	String	city name.
street	String	street name.
number	String	street number.

Parameter	Required	Type	Description
orderId		String	order identity number (Required only when object is provided)
shippingInfo		JSON	shipping info

Parameter	Type	Description
name	String	shipping name
phone	String	phone number
email	String	email address
address	JSON	the same as billingAddress

Parameter	Type	Description
cardHolderName	String	Cardholder's full name.
cardNumber	String	16 digit number of the card, as a string without any separators.
expirationMonth	Integer	2 digit number representing the card's expiration month.
expirationYear	Integer	4 digit number representing the card's expiration year.
cvc	String	Credit card verification code.

Parameter	Required	Type	Description
ipAddress		String	Payer's IP address
customProperties		JSON	Key/value pairs used to store additional custom metadata

Parameter	Type	Description
transferStatus	String	Transfer status, SETTLED, IN_PROGRESS, AUTHORIZED, FAILED
transferStatusCode	int	Transfer status code, 200 transaction SETTLED, IN_PROGRESS or AUTHORIZED, other FAILED
transferErrorMsg	String	Transfer error message if failed
referenceId	String	Unique key to payment ticket, generated by Liquido.
idempotencyKey	String	Unique key to ensure idempotent requests. given by the merchant in their system
amount	Long	The transfer amount
country	String	country code
currency	String	The currency code of the transferred fund
finalAmount	Long	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 method, enum value as CREDIT_CARD, PIX_STATIC_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

Parameter	Type	Description
cardInfo	JSON	card detail info
cardId	String	card id, can use it to create a card payment instead of card info
installments	Integer	number of installments

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.
CHARGED_BACK	The transaction of this payment has been reported as chargeback.
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.