Tokenize
Use Payment Gateway API to store information for future transactions.
To send a tokenize request with the Maast Payment Gateway API, see the guide below. Depending on its configuration, a tokenize request either (1) saves card or ACH payment information to a new card ID, or (2) updates information saved to an existing card ID. This is separate from Customer Vault storage; see Payment Method Storage for more information. See Tokenize in our API Reference for field definitions.
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.)
Implement
Write a POST request to send to the /pg/tokenize
endpoint, including your sandbox merchant ID in the body. See the following sample code:
curl --request POST \
--url https://api-test.maast.com/pg/tokenize \
--header 'accept: application/json' \
--header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
--header 'content-Type: application/json' \
--data '
{
"merchant_id": "<Provide merchant ID that links to API Key>"
}
'
Now you are ready to configure your request. The sections below describe the types of data you can include in your tokenize request. See Tokenize in API Reference for field definitions.
Merchant and Integrator Information
Use the fields in the following sample code to add information to the body of the request that associates the tokenized information with additional merchant information. This is helpful if you have more than one Payment Gateway profile or store location. If you are an integrator, you must include your integrator ID in the vendor_id
field:
{
"merchant_id": "210000000289",
"profile_id": "21200001000300000978",
"developer_id": "CompanyV1.2",
"loc_id": "0001",
"vendor_id": 212100026512
}
Card Information
Use the fields in the following sample code to add card authorization information to the body of the request:
{
"cardholder_name": "JOHN CUSTOMER",
"avs_address": "123 Main St",
"avs_zip": "94402",
"email_address": [
"[email protected]",
"[email protected]"
],
"card_number": "4111111111111111",
"exp_date": "0930"
"cvv2": "152",
"card_id": "86e1b00d9b0811e68df3069d8f743581",
"card_swipe": ";4111111111111111=08051010912345678901?8",
"client_ip": "10.1.1.4"
}
ACH Information
Use the fields in the following sample code to add ACH payment information to the body of the request:
{
"tr_number": "011111111",
"dda_number": "3456776866",
"type_id": "S",
"cardholder_name": "JOHN CUSTOMER"
}
Google Pay™ Authorization
Use the fields in the following sample code to add authorization information for Google Pay™ or Apple Pay™ to the body of the request:
{
"payload_google_pay": "xxxxxxx",
"payload_apple_pay": "xxxxxxx"
}
Note: If you wish to use Apple Pay™, please contact Maast Support.
Response Information
Use the fields in the following sample code to configure your transaction response:
{
"single_use": true,
"echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]",
"session_id": "string",
"user_id": 0,
"report_data": "[ {\"shipping address\" : \"123 Main St.\"},{\"shipping city, state zip\" : \"San Mateo, CA 94402\"} ]"
}
Example Requests
Once configured, the code for your API tokenize request will resemble one of the following examples.
Below is a sample request to tokenize a new payment card:
curl --request POST \
--url https://api-test.maast.com/pg/tokenize \
--header 'accept: application/json' \
--header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
--header 'content-Type: application/json' \
--data '
{
"exp_date": "0930",
"merchant_id": "210000000289",
"card_number": "4111111111111111",
"cvv2": "152",
"avs_address": "123 Main St",
"avs_zip": "94402",
"email_address": [
"[email protected]",
"[email protected]"
]
}
'
Below is a sample request to update the information on a payment card that is already tokenized:
curl --request POST \
--url https://api-test.maast.com/pg/tokenize \
--header 'accept: application/json' \
--header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
--header 'content-Type: application/json' \
--data '
{
"exp_date": "0930",
"merchant_id": "210000000289",
"card_number": "4111111111111111",
"card_id": "86e1b00d9b0811e68df3069d8f743581"
}
'
Below is a sample request to tokenize new ACH payment information:
curl --request POST \
--url https://api-test.maast.com/pg/tokenize \
--header 'Accept: application/json' \
--header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
--header 'Content-Type: application/json' \
--data '
{
"exp_date": "0930",
"merchant_id": "210000000289",
"tr_number": "011111111",
"dda_number": "3456776866",
"type_id": "S",
"cardholder_name": "JOHN CUSTOMER"
}
'
Integrate
Send a POST request to the /pg/tokenize
endpoint with your configurations in the body.
Maast will return a response like the code below:
{
"rcode": "000",
"rmsg": "Token request complete",
"pg_id": "d24ac6189b0b11e6966ca68d5edbef41",
"card_id": "86e1b00d9b0811e68df3069d8f743581",
"card_number": "4111xxxxxx111111",
"echo_fields": "[ {\"product\" : \"lawnmower\"},{\"purchase\" : \"1 yr maintenance\"} ]"
}
Check the rcode
field. 000
confirms a successful transaction. If rcode
is a value other than 000
, check Payment Gateway API Response Codes in Reference. See Tokenize in API Reference for response field definitions.
Test and Go Live
See our Test and Go Live guide to test your API integration and to start transacting with an active production account.
Updated 9 months ago