APIs
This section describes the available APIs and their usage.
note
Base URL for the API requests will be https://merchant-api.globiancepay.com/merchant-api-service
Create Checkout
The create-checkout API allows you to create a new checkout.
Endpoint: /create-checkout
Method: POST
Request Body
The request body should include the following parameters:
amount(number): The amount for the checkout. It should be a numeric value greater than zero.currency(string): The currency for the checkout. It should be one of the allowed request currencies ("USD" OR "EUR").itemName(string, optional): The name of the item associated with the checkout.itemId(string, optional): The ID of the item associated with the checkout.note(string, optional): Additional note for the checkout.clientId(string, optional): The ID of the client associated with the checkout.items(array): Array of item included in checkout.
Example Request:
const createCheckout = async () => {
try {
const response = await axiosInstance.post("/create-checkout", {
amount: 250,
apiKey:"684315e5-7f83-446a-bb8b-64fc95c0fc4d",
currency:"USD",
itemName:"Ginger Tea",
note: "Additional note",
itemId: "xyz123",
items:[
{
itemName: "Test Item",
price: 50,
qty: 5,
taxRate: 1.5
}
],
note:"Test payment"
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
createCheckout();
Example Response:
{
"quotes": [],
"payments": [],
"items": [
{
"itemName": "Test Item",
"price": 50,
"qty": 5,
"taxRate": 1.5,
"taxAmount": 3.75,
"subTotal": 250,
"total": 253.75
}
],
currencies: [
{
"currencyId": "d6a93955-5e65-48f4-8c5e-68c1a7dc30a5",
"currencyName": "USDG",
"currencyFullName": "Globiance USD Stablecoin",
"currencyType": "blockchain",
"currencyNetwork": null
},
{
"currencyId": "d6a93955-5e65-48f4-8c5e-68c1a7dc30a5",
"currencyName": "USDG",
"currencyFullName": "Globiance USD Stablecoin",
"currencyType": "wallet",
"currencyNetwork": null
},
{
"currencyId": "2fa87932-da60-4427-894a-986775c292da",
"currencyName": "TRX",
"currencyFullName": "TRON",
"currencyType": "blockchain",
"currencyNetwork": null
},
{
"currencyId": "2fa87932-da60-4427-894a-986775c292da",
"currencyName": "TRX",
"currencyFullName": "TRON",
"currencyType": "wallet",
"currencyNetwork": null
},
{
"currencyId": "20849003-e854-4c2d-84f1-1025caba56d8",
"currencyName": "BTC",
"currencyFullName": "Bitcoin",
"currencyType": "wallet",
"currencyNetwork": null
},
{
"currencyId": "e591415d-683b-47fa-a2cb-faf7a5b9cc65",
"currencyName": "EURG",
"currencyFullName": "Globiance EUR Stablecoin",
"currencyType": "blockchain",
"currencyNetwork": null
},
{
"currencyId": "e591415d-683b-47fa-a2cb-faf7a5b9cc65",
"currencyName": "EURG",
"currencyFullName": "Globiance EUR Stablecoin",
"currencyType": "wallet",
"currencyNetwork": null
},
{
"currencyId": "c7a82c43-7e48-4012-a70e-6e2e2b61d58f",
"currencyName": "USDT",
"currencyFullName": "Tether USD",
"currencyType": "wallet",
"currencyNetwork": null
},
{
"currencyId": "c7a82c43-7e48-4012-a70e-6e2e2b61d58f",
"currencyName": "USDT",
"currencyFullName": "Tether USD",
"currencyType": "blockchain",
"currencyNetwork": "TRX"
},
{
"currencyId": "eb68220f-c269-428e-9c1f-d59846b55e49",
"currencyName": "XDC",
"currencyFullName": "XinFin Network",
"currencyType": "wallet",
"currencyNetwork": null
},
{
"currencyId": "eb68220f-c269-428e-9c1f-d59846b55e49",
"currencyName": "XDC",
"currencyFullName": "XinFin Network",
"currencyType": "blockchain",
"currencyNetwork": "XDC"
},
{
"currencyId": "20849003-e854-4c2d-84f1-1025caba56d8",
"currencyName": "BTC",
"currencyFullName": "Bitcoin",
"currencyType": "blockchain",
"currencyNetwork": null
}
],
"enableFIATBuy": true,
"requestCurrency": "USD",
"requestCurrencyAmount": 253.75,
"requestCurrencyPriceUsd": 1,
"amountInUSD": 253.75,
"duration": 1800000,
"checkoutTime": "2024-10-15T11:07:03.846Z",
"expiryTime": "2024-10-15T11:37:03.846Z",
"note": "Test Payment",
"clientId": null,
"itemId": null,
"itemName": "Ginger Tea",
"status": "pending",
"checkoutId": "b02d7b3e-94c2-4c89-a4f2-e010e59ebf42"
}
Create Invoice Checkout
The create-invoice-checkout API allows you to create a new checkout just like create-checkout but additionally creates a payment link which can be shared to your client for payment.
If you pass an email , globiance will also send a mail containing payment link to that email.
Endpoint: /create-invoice-checkout
Method: POST
Request Body
The request body should include the following parameters:
amount(number): The amount for the checkout. It should be a numeric value greater than zero.currency(string): The currency for the checkout. It should be one of the allowed request currencies ("USD" OR "EUR").itemName(string, optional): The name of the item associated with the checkout.itemId(string, optional): The ID of the item associated with the checkout.note(string, optional): Additional note for the checkout.clientId(string, optional): The ID of the client associated with the checkout.items(array): Array of item included in checkout.email( optional ): Email address where you want to send this invoicecheckoutDuration( optional ): Duration for which this checkout link will be valid in milliseconds. Default is 30 dayslanguage( optional ): Default language in which the invoice will be shown. Below are the various valid options:en: Englishar: Arabicde: Germanzh-cn: Chinese (Simplified)es: Spanishfr: Frenchit: Italianja: Japaneseko: Koreanpt: Portuguesetr: Turkish
Example Request:
const createInvoiceCheckout = async () => {
try {
const response = await axiosInstance.post("/create-invoice-checkout", {
amount: 250,
apiKey:"684315e5-7f83-446a-bb8b-64fc95c0fc4d",
currency:"USD",
itemName:"Ginger Tea",
note: "Additional note",
itemId: "xyz123",
items:[
{
itemName: "Test Item",
price: 50,
qty: 5,
taxRate: 1.5
}
],
note:"Test payment",
email:"john@example.com",
checkoutDuration: 30*60*1000
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
createInvoiceCheckout();
Example Response:
The API will respond with the created checkout details.
{
"message": "checkout created",
"data": {
"quotes": [
{
"currencyId": "AC90FA93-754C-4B36-9E62-A3AAD96B27ED",
"currencyName": "XDC",
"currencyType": "wallet",
"currencyFullName": "XinFin Network",
"network": null,
"feePercent": 1,
"amount": 6114.8674452,
"fee": 61.14867445,
"total": 6176.01611965
}
],
"payments": [],
"items": [
{
"itemName": "Test Item",
"price": 50,
"qty": 5,
"taxRate": 1.5,
"taxAmount": 3.75,
"subTotal": 250,
"total": 253.75
}
],
"requestCurrency": "USD",
"requestCurrencyAmount": 253.75,
"requestCurrencyPriceUsd": 1,
"amountInUSD": 253.75,
"duration": 1800000,
"checkoutTime": "2023-10-19T11:41:50.181Z",
"expiryTime": "2023-10-19T12:11:50.181Z",
"note": "Test payment",
"clientId": null,
"itemId": null,
"itemName": "Ginger Tea",
"status": "pending",
"checkoutId": "63adb2cb-27a8-45b1-ab1a-f47ecde31ae8"
},
paymentLink: "https://invoice.globiance.com/?checkoutId=828a66b7-cc96-4c55-b43d-8afca5a2166f&apiKey=01259e6d-0369-4ff0-8b9c-4481f43239d9"
}
Generate Quote
The generate-quote API allows you to retrieve a quote for a specific currency and checkout.
To generate address this api is pre-requisites first you need to fetch quote then on basis of this you can make a call to generate address.
Endpoint
/generate-quote
Method
POST
Request Body
The request body must include the following parameters:
currencyId(string): The unique identifier for the currency.apiKey(string): Your API key for authentication.checkoutId(string): The ID of the checkout for which the quote is being generated.currencyType(string): The type of currency being used. For blockchain currencies, specify"blockchain".
Example Request
const generateQuote = async () => {
try {
const response = await axiosInstance.post("/generate-quote", {
currencyId: "eb68220f-c269-428e-9c1f-d59846b55e49",
apiKey: "dbb04ff6-f419-46b4-990c-f99fe11bb660",
checkoutId: "44b19e4a-fab6-4433-98ad-b567f9487edb",
currencyType: "blockchain"
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
generateQuote();
Example Response
Upon a successful request, the API will respond with details of the generated quote:
{
"currencyId": "eb68220f-c269-428e-9c1f-d59846b55e49",
"currencyName": "XDC",
"currencyType": "blockchain",
"currencyFullName": "XinFin Network",
"network": null,
"currencyNetwork": null,
"feePercent": 0,
"fee": 0,
"baseAmount": 101.4,
"amount": 101.4,
"subTotal": 101.4,
"networkSurchargeAmountUsd": 0,
"networkSurchargeAmount": 0,
"total": 101.4
}
Generate Address
The generate-address API allows you to generate an address for a specific checkout.
Before this api you need to fetch Quote using Generate-Quote api.
Endpoint: /generate-address
Method: POST
Request Body
The request body should include the following parameters:
currencyId(string): The ID of the currency associated with the checkout.checkoutId(string): The ID of the checkout for which the address is generated.network(string, optional): The network for the address (if applicable).
Example Request:
const generateAddress = async () => {
try {
const response = await axiosInstance.post("generate-address", {
currencyId: "c123",
checkoutId: "checkout123",
network: "Ethereum"
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
generateAddress();
Example Response:
The API will respond with the generated address details.
{
"message": "successfully got the address",
"data": {
"address": "xdc85d4485040b5870c2f3b8a66cef7d08fe9c8dec1",
"destinationTag": null
}
}
Cancel Checkout
The cancel-checkout API allows you to generate an address for a specific checkout.
Endpoint: /cancel-checkout
Method: POST
Request Body
The request body should include the following parameters:
checkoutId(string): The ID of the checkout to cancel.
Example Request:
const cancelCheckout = async () => {
try {
const response = await axiosInstance.post("cancel-checkout", {
checkoutId: "checkout123"
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
cancelCheckout();
Example Response:
The API will respond with the cancel checkout message.
{
"message": "checkout cancelled"
}
Get Checkout Details
The get-checkout-details API allows you to generate an address for a specific checkout.
Endpoint: /get-checkout-details
Method: POST
Request Body
The request body should include the following parameters:
checkoutId(string): The ID of the checkout to retrieve details.
Example Request:
const getCheckoutDetails = async () => {
try {
const response = await axiosInstance.post("get-checkout-details", {
apiKey: "API_KEY",
checkoutId: "63adb2cb-27a8-45b1-ab1a-f47ecde31ae8",
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
getCheckoutDetails();
Example Response:
The API will respond with the checkout details.
{
"data": {
"currencies": [...],
"payments": [],
"store": {
"logo": "https://merchant-api.globiancepay.com/merchant-dashboard-api-service/merchant-logo/9da84c8f-dbd6-4392-a418-4ce1025fb3f3.png",
"labelName": "Mega Store",
"apiKey": "684315e5-7f83-446a-bb8b-64fc95c0fc4d",
"isActive": true,
"taxId": null,
"showTaxId": false,
"taxRate": 0
},
"items": [
{
"itemName": "Test Item",
"itemId": null,
"price": 50,
"qty": 5,
"taxRate": 1.5,
"taxAmount": 3.75,
"subTotal": 250,
"total": 253.75
}
],
"requestCurrency": "USD",
"requestCurrencyAmount": 253.75,
"requestCurrencyPriceUsd": 1,
"amountInUSD": 253.75,
"duration": 1800000,
"checkoutTime": "2023-10-19T11:41:50.181Z",
"expiryTime": "2023-10-19T12:11:50.181Z",
"note": "Test payment",
"clientId": null,
"itemId": null,
"itemName": "Ginger Tea",
"status": "pending",
"checkoutId": "63adb2cb-27a8-45b1-ab1a-f47ecde31ae8"
}
}
Get Payment Details
The get-payment-details API allows you to generate an address for a specific checkout.
Endpoint: /get-payment-details
Method: POST
Request Body
The request body should include the following parameters:
paymentId(string): The ID of the payment to retrieve details.
Example Request:
const getPaymentDetails = async () => {
try {
const response = await axiosInstance.post("get-payment-details", {
paymentId: "payment123"
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
getPaymentDetails();
Example Response:
The API will respond with the payment details.
{
"data": {
"paymentId": "a596ef60-ffb1-11ed-b395-4318d66a581b",
"currencyId": "AC90FA93-754C-4B36-9E62-A3AAD96B27ED",
"currencyName": "XDC",
"createdAt": "2023-05-31T12:49:57.078Z",
"amount": 328.19740551062,
"status": "confirmed",
"isUnderDispute": false,
"disputeType": null,
"transactionType": "wallet",
"transactionDetail": {
"amount": 328.19740551062,
"payerUserId": "4C5ABF65-0A54-4BC6-93F7-4B10689BC780",
"payerEmail": "gb***************"
},
"paymenStatusHistory": [
{
"paymentId": "a596ef60-ffb1-11ed-b395-4318d66a581b",
"action": "processing",
"metadata": null,
"createdAt": "2023-05-31T12:49:57.089Z"
},
{
"paymentId": "a596ef60-ffb1-11ed-b395-4318d66a581b",
"action": "confirmed",
"metadata": null,
"createdAt": "2023-05-31T12:49:57.095Z"
},
{
"paymentId": "a596ef60-ffb1-11ed-b395-4318d66a581b",
"action": "settled",
"metadata": null,
"createdAt": "2023-05-31T12:49:57.271Z"
}
]
}
}
Create User Subscription
Endpoint: /create-user-subscription
Method: POST
Description: Creates a new user subscription.
Request Body:
planId(string, UUID): The ID of the subscription plan.customerId(string): The ID of the customer.customerEmail(string): The email address of the customer.startsAt(string, optional): The start date of the subscription.note(string, optional): Additional notes for the subscription. Must be a valid JSON string.
Example Request:
{
"planId": "123e4567-e89b-12d3-a456-426614174000",
"customerId": "cust123",
"customerEmail": "customer@example.com",
"startsAt": "2023-08-01T00:00:00Z",
"note": "{"key":"value"}"
}
Response:
{
"message": "subscription created",
"data": {
"link": "https://subscription.globiance.dev/subscription/6ae4d823-ae90-4de7-a325-9779e3da0bc1",
"subscriptionUserId": "6ae4d823-ae90-4de7-a325-9779e3da0bc1"
}
}
Get User Subscription
Endpoint: /get-user-subscription
Method: POST
Description: Retrieves the details of a user subscription.
Request Body:
userSubscriptionId(string, UUID): The ID of the user subscription.
Example Request:
{
"userSubscriptionId": "123e4567-e89b-12d3-a456-426614174000"
}
Response:
{
"data": {
"planId": "6ae4d823-ae90-4de7-a325-9779e3da0bc1",
"customerId": "XXX-TEA-STORE-XXX-002",
"customerEmail": "xyz@xyz.com",
"status": "pending",
"planCyclePeriod": "W",
"planCycle": 1,
"planStart": "2024-08-12T07:24:48.031Z",
"planEnd": "2024-09-23T07:24:48.031Z",
"planCost": 100,
"planCurrency": "USD",
"planGraceTime": 2,
"planGraceTimePeriod": "D",
"planGracePeriodType": "post-period",
"totalPaidCycles": 0,
"remainingCycles": 6,
"prepaidSubscriptionStarts": null,
"prepaidSubscriptionEnds": null,
"nextPaymentOn": null
}
}
Pause User Subscription
Endpoint: /pause-user-subscription
Method: POST
Description: Pauses an active user subscription.
Request Body:
userSubscriptionId(string, UUID): The ID of the user subscription.
Example Request:
{
"userSubscriptionId": "123e4567-e89b-12d3-a456-426614174000"
}
Response:
{
"subscriptionId": "sub123",
"status": "paused",
"message": "Subscription paused successfully."
}
Resume User Subscription
Endpoint: /resume-user-subscription
Method: POST
Description: Resumes a paused user subscription.
Request Body:
userSubscriptionId(string, UUID): The ID of the user subscription.
Example Request:
{
"userSubscriptionId": "123e4567-e89b-12d3-a456-426614174000"
}
Response:
{
"subscriptionId": "sub123",
"status": "active",
"message": "Subscription resumed successfully."
}
Cancel User Subscription
Endpoint: /cancel-user-subscription
Method: POST
Description: Cancels an active user subscription.
Request Body:
userSubscriptionId(string, UUID): The ID of the user subscription.
Example Request:
{
"userSubscriptionId": "123e4567-e89b-12d3-a456-426614174000"
}
Response:
{
"subscriptionId": "sub123",
"status": "canceled",
"message": "Subscription canceled successfully."
}