Guides

Create a Checkout Link

Use our API to generate a dynamic Checkout link to a hosted page.

Suggest Edits

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

  1. See Create a Sandbox Account to sign up and log in to the Maast Manager portal.

  2. Follow the steps in Get Your API Credentials to save a sandbox ID and API key.

  3. 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.)

  4. 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).

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 a preferences object containing allow_save_card set to true.

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 and customer_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 a preferences object containing allow_save_card set to true.

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 and customer_last_name and/or customer_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 a preferences object containing allow_save_card set to true.

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 the customer_id. (A card_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 about 1 year ago