Create a Checkout Link
Use our API to generate a dynamic Checkout link to a hosted page.
This guide shows you how to use the Checkout API resource to create a dynamic checkout link for a hosted page or modal containing a checkout form. Depending on the request configuration, the generated link can be used to make a payment or to add or edit saved payment methods in Customer Vault.
See Create a Checkout Link in API Reference for field definitions. For more information on using the resource for ACH payments, see Checkout API Conventions for ACH.
Prerequisites
-
See Create a Sandbox Account to sign up and log in to the Maast Manager portal.
-
Follow the steps in Get Your API Credentials to save a sandbox ID and API key.
-
See Authentication to format the credentials and generate your API token. (Alternatively, use the credentials as-is to test this endpoint with our 'Try It!' feature.)
-
Do one of the following:
- Follow the steps in Create a Dynamic Checkout Profile to create a checkout profile and save its unique checkout profile ID (
checkout_profile_id
). - If you intend to use the link to add or edit saved payment methods in Customer Vault, follow the steps in the Dynamic Link Method: Customer Vault guide to create a hosted vault-type checkout profile and save its unique checkout profile ID (
checkout_profile_id
).
- Follow the steps in Create a Dynamic Checkout Profile to create a checkout profile and save its unique checkout profile ID (
Implement
Write a POST request to send to the /platform/checkout
endpoint. See the sample code below:
curl --request POST \
--url https://api-test.maast.com/platform/checkout \
--header 'accept: application/json' \
--header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
--header 'content-type: application/json'
You can configure your request by including several possible fields in the request body. The fields are categorized below. Note that certain fields are required for requests involving Customer Vault or if you have multiple profiles; see this endpoint's API Reference for details and field descriptions.
Customer Information
You can add several fields of customer information in the request body to pre-fill the hosted form. See the sample code below:
{
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_firm_name": "Your Business",
"customer_email": "[email protected]",
"customer_id": "JOHNDOE",
"card_id": "86e1b00d9b0811e68df3069d8f743581",
"customer_phone": 447999999999,
"billing_addr1": "123 Main Street",
"billing_state": "CA",
"billing_city": "San Mateo",
"billing_zip": "94538"
}
Link Generation
See the following subsections to generate the type of link you want:
To Make a Payment
If you intend the link to be used to make a payment, do the following:
- Use a dynamic checkout profile ID (
checkout_profile_id
) in the body of the request. (This is required if you have more than checkout profile.) - Add
amt_tran
with the preset amount for the transaction. - Optionally, add relevant fields to the request body such as the currency and type of transaction.
See the sample code below:
{
"checkout_profile_id": 1005
"amt_tran": 456,
"tran_currency": "840",
"moto_ecomm_ind": "1"
}
To Save a New Payment Method
If you intend the link to be used to add a new profile to Customer Vault, include one of the following in the request body:
- A vault-type checkout profile ID (
checkout_profile_id
), or - A dynamic checkout profile ID (
checkout_profile_id
) and apreferences
object containingallow_save_card
set totrue
.
Then do the following:
- Create a customer ID (up to 32AN) and use it for
customer_id
in the request body. - Include at least one of the following field sets in the body of the request:
customer_first_name
andcustomer_last_name
customer_firm_name
To Update Payment Details
If you intend the link to be used to add a payment method to an existing Customer Vault profile, include one of the following in the request body:
- A vault-type checkout profile ID (
checkout_profile_id
), or - A dynamic checkout profile ID (
checkout_profile_id
) and apreferences
object containingallow_save_card
set totrue
.
Then do the following:
- Include the customer's ID (
customer_id
) in the request body. - To reduce the amount of information your customer must enter, you may include
customer_first_name
andcustomer_last_name
and/orcustomer_firm_name
.
See the sample code below:
{
"checkout_profile_id": 1005
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_firm_name": "Your Business",
"customer_id": "JOHNDOE",
"preferences": {
"allow_save_card": true
}
}
If you intend the link to be used to update a payment method for an existing Customer Vault profile, include one of the following in the request body:
- A vault-type checkout profile ID (
checkout_profile_id
), or - A dynamic checkout profile ID (
checkout_profile_id
) and apreferences
object containingallow_save_card
set totrue
.
Then do the following:
- Include the customer's ID (
customer_id
) in the request body. - Include in the request body a
card_id
that is associated with thecustomer_id
. (Acard_id
was created when you added the payment method to the Customer Vault profile. See the Add a Payment Method guide for more information.)
See the following sample code:
{
"checkout_profile_id": 1005
"customer_id": "JOHNDOE",
"card_id": "86e1b00d9b0811e68df3069d8f743581",
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_firm_name": "Your Business",
"customer_email": "[email protected]",
"customer_id": "JOHNDOE",
"customer_phone": 447999999999,
"billing_addr1": "123 Main Street",
"billing_state": "CA",
"billing_city": "San Mateo",
"billing_zip": "94538"
}
Form Settings
Add fields to the request body to further configure the hosted checkout form. See the sample code below:
{
"purchase_id": "PID#2345",
"profile_id": "21200000000100000840",
"merch_ref_num": "REF#1234",
"preferences": {
"success_url": "https:/yourcompany.com/payment/success",
"failure_url": "https://yourcompany.com.com/payment/fail",
"allow_partial_payments": false,
"allow_save_card": false,
"allow_ach_payment": true,
"email_receipt": false,
"request_type": "sale",
"expire_in_secs": 6000
}
}
Example Request
Once configured, your request will resemble the sample code below:
curl --request POST \
--url https://api-test.maast.com/platform/checkout \
--header 'accept: application/json' \
--header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
--header 'content-type: application/json' \
--data '
{
"amt_tran": 4.56,
"tran_currency": "840",
"purchase_id": "PID#2345",
"profile_id": "21200000000100000840",
"merch_ref_num": "REF#1234",
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_firm_name": "Your Business",
"customer_email": "[email protected]",
"customer_id": "JOHNDOE",
"card_id": "86e1b00d9b0811e68df3069d8f743581",
"customer_phone": 447999999999,
"billing_addr1": "123 Main Street",
"billing_state": "CA",
"billing_city": "San Mateo",
"billing_zip": "94538",
"moto_ecomm_ind": "1",
"preferences": {
"success_url": "https:/yourcompany.com/payment/success",
"failure_url": "https://yourcompany.com.com/payment/fail",
"allow_partial_payments": false,
"allow_save_card": true,
"allow_ach_payment": true,
"email_receipt": false,
"request_type": "sale",
"expire_in_secs": 6000
},
"checkout_profile_id": 1005
}
'
Integrate
Send your configured request. You will receive a response like this from the Maast server:
{
"code": 0,
"message": "Success",
"data": {
"checkout_id": "a393941797c811e6825102a019999999",
"checkout_link": "https://app.qualpay.com/checkout/a393941797c811e6825102a019999999",
"merchant_id": 212000000001,
"purchase_id": "PID#2345",
"amt_tran": 4.56,
"tran_currency": "840",
"db_timestamp": "2025-02-21T12:57:47.000-0700",
"expiry_time": "2025-02-21T14:37:47.000-0700"
}
}
Check the code
field in the request response: 0
confirms success. If the value is something other than 0
, check Platform API Response Codes in Reference. See Create a Checkout Link in our API Reference for field definitions.
The URL in the checkout_link
field can now be used. It will expire when used or at the time displayed in expiry_time
, whichever comes first.
Test and Go Live
See our Test and Go Live guide to test your dynamic link integration and to start transacting with an active production account.
Change all endpoints and credentials
To start using your production account, you must:
- Go through your integration and change all your credentials to use your production API token.
- Go through your integration and change all endpoints from the test base path (
https://api-test.maast.com
) to the production base path:https://api.maast.com
.
Updated 11 months ago