Create A Payment
Create A Credit Card Payment¶
When sending a credit card payment request over to Liquido, the card information details need to be included. The card information details can be sent with card info or cardId. See more about how to create a cardId.
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
{
"idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
"amount": 100,
"currency": "BRL",
"country": "BR",
"paymentMethod": "CARD",
"paymentFlow": "DIRECT",
"payer": {
"name": "username",
"email": "username@liquido.com",
"document": {
"documentId": "53012345678",
"type": "CPF"
},
"phone": "+55 81987654321",
"billingAddress": {
"zipCode": "04849333",
"state": "SP",
"city": "sao paulo",
"district": "Jardim Gaivotas",
"street": "Rua 9 de setembro",
"number": "15",
"complement": "casa",
"country": "BR"
}
},
"card": {
"cardHolderName": "card_holder_name",
"cardNumber": "4242424242424242",
"expirationMonth": "09",
"expirationYear": "2024",
"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": "BR"
}
}
},
"description": "this is a test pay",
"callbackUrl": "https://api.client.com/callback/",
"subMerchantId": "UUID"
}
Create a card payment with card id¶
How to get a card id?
Please see here for further details.
Request Body
{
"idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
"amount": 100,
"currency": "BRL",
"country": "BR",
"paymentMethod": "CARD",
"paymentFlow": "DIRECT",
"payer": {
"name": "username",
"email": "username@liquido.com",
"document": {
"documentId": "53012345678",
"type": "CPF"
},
"phone": "+55 81987654321",
"billingAddress": {
"zipCode": "04849333",
"state": "SP",
"city": "sao paulo",
"district": "Jardim Gaivotas",
"street": "Rua 9 de setembro",
"number": "15",
"complement": "casa",
"country": "BR"
}
},
"cardId": "8736453a-dad0-4f26-85f0-95e8787d0237",
"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": "BR"
}
}
},
"description": "this is a test pay",
"callbackUrl": "https://api.client.com/callback/",
"subMerchantId": "UUID"
}
Response
{
"transferStatusCode": 200,
"transferErrorMsg": null,
"idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
"referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
"paymentMethod": "CARD",
"amount": 100,
"currency": "BRL",
"country": "BR",
"finalAmount": 100,
"finalCurrency": "BRL",
"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",
"document": {
"documentId": "53012345678",
"type": "CPF"
},
"phone": "+55 81987654321",
"billingAddress": {
"zipCode": "04849333",
"state": "SP",
"city": "sao paulo",
"district": "Jardim Gaivotas",
"street": "Rua 9 de setembro",
"number": "15",
"complement": "casa",
"country": "BR"
}
},
"transferDetails": {
"card": {
"cardInfo": {
"cardHolderName": "card_holder_name",
"expirationMonth": 9,
"expirationYear": 2024,
"brand": "VISA",
"bin": "458124",
"last4": "0000"
},
"cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
}
},
"transferStatus": "SETTLED",
"description": "this is a test pay",
"callbackUrl": "https://api.client.com/callback/",
"subMerchantId": "UUID"
}
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": "CARD",
"amount": 100,
"currency": "BRL",
"country": "BR",
"finalAmount": 100,
"finalCurrency": "BRL",
"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:59:59 GMT-08:00",
"payer": {
"name": "username",
"email": "username@liquido.com",
"document": {
"documentId": "53012345678",
"type": "CPF"
},
"phone": "+55 81987654321",
"billingAddress": {
"zipCode": "04849333",
"state": "SP",
"city": "sao paulo",
"district": "Jardim Gaivotas",
"street": "Rua 9 de setembro",
"number": "15",
"complement": "casa",
"country": "BR"
}
},
"transferDetails": {
"card": {
"cardInfo": {
"cardHolderName": "card_holder_name",
"expirationMonth": 9,
"expirationYear": 2024,
"brand": "VISA",
"bin": "458124",
"last4": "0000"
},
"cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
}
},
"transferStatus": "SETTLED",
"description": "this is a test pay",
"callbackUrl": "https://api.client.com/callback/",
"subMerchantId": "UUID"
}
}
}
Chargeback¶
Please see here for further details.
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=1BRL | |
country | String | country code | |
currency | String | The currency code of the transferred fund | |
paymentMethod | String | payment method, enum value as 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 | |
description | String | description of payment | |
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. | |
riskData | JSON | The risk data of the payment. MERCHANT_APP_NAME or MERCHANT_WEBSITE must be provided in risk Data. Please see here for further details. |
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). | |
String | email. | ||
phone | String | Mobile phone number. Should include “+55” as a prefix. | |
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. | |
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. | |
cvc | String | Credit card verification code. | |
expirationMonth | String | 2 digit numbers representing the card's expiration month. | |
expirationYear | String | 4 digit numbers representing the card's expiration year. |
Response Body Parameters¶
Parameter | Type | Description |
---|---|---|
transferStatus | String | Transfer status |
transferStatusCode | Integer | Transfer status code, 200 transaction SETTLED, IN_PROGRESS or AUTHORIZED, other FAILED |
transferErrorMsg | String | Provide detailed error messages if payments fail. Please refer to the descriptions of the relevant status codes for 2xxx. |
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 CARD |
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. |
createdTime | String | Payment ticket created time |
scheduledTime | String | Payment ticket scheduled time |
finalStatusTime | String | Transfer final status update time, final status include SETTLED, FAILED |
subMerchantId | String | The sub merchant ID. |
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. Returned when paid with card ID, not returned when paid with 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 | 1 or 2 digit number(s) representing the card's expiration month. |
expirationYear | Integer | 4 digit numbers 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_AUTHORIZED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;
More Credit Card Features¶
Create A Credit Card Authorization¶
Please see here for further details.
Create A Credit Card Payment With 3D-Secure¶
Please see here for further details.
Create A Credit Card Payment With Installments¶
Please see here for further details.
Create A Credit Card Payment With Risk Data¶
Please see here for further details.
Create A Credit Card Redirect Payment¶
Please see here for further details.