For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Hosted Fields - Tokenization Guide

Manage your customers payment experience with hosted fields

Save card details to our vault

To save a customer's card details to our vault or to verify that a customer's account is valid, send a CreateAuth request.

Note: This transaction is also known as a zero dollar authorization or an address verification transaction.

How it works

Program the POS to send a CreateAuth request to the relevant endpoint. Depending on your request, our gateway returns the following:

If you send true for the create_token field, our gateway tokenizes the customer's card details and returns the token in the response.
If you send true for the address_verification_service field, our gateway runs an AVS check and returns the result in the response.

Program the POS to send a CreateSale request to the relevant endpoint.

Scenario	Merchant uses the POS to:
A customer wants to purchase goods.	Take a dollar amount from the customer's account.
A merchant wants to save a customer's card details to use for future transactions.	Run an authorization for $0.00.

Important things to consider

If the transaction declines, our gateway still generates a token.
You can't send a CreateAuth request for more than $0.00.

Sample request

Content-Type: application/json
Authorization: AuthToken {AuthTokenV2}
X-GP-Request-Id: {request_id}
X-GP-Version: 2021-04-08
X-GP-Api-Key: {API Key}
X-GP-Partner-App-Name: {Name of integrating application}
{
  "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
  "card": {
    "temporary_token": "111xx111-x11x-1xx1-1111-x11x1111x11x"
  },
  "customer": {
    "billing_address": {
      "line1": "8200 Central Ave.",
      "postal_code": "94560"
    }
  },
  "payment": {
    "amount": "0.00",
    "currency_code": "840"
  },
  "transaction": {
    "country_code": "840",
    "processing_indicators": {
      "create_token": true,
      "address_verification_service": true,
      "generate_receipt": true
    }
  }
}

Sample response

{
    "creditauth_id": "000000084345",
    "status": "approved",
    "approval_code": "007831",
    "processor_response": "000AP",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "cardholder_name": "test name",
        "expiry_month": "12",
        "expiry_year": "25",
        "token": "4Z3u3P55Fx",
        "type": "visa"
    },
    "payment": {
        "amount": "0.00",
        "currency_code": "840",
        "type": "credit"
    },
    "transaction": {
        "entry_type": "keyed",
        "language": "en-US"
    },
    "reference_id": "MER-4f1f1128-aee1-4d6b-bf2d-128269e8d19a"
}

Running a Sale with a Token

To take a dollar amount from a customer's account using saved card details, send a CreateSale request to the relevant endpoint.

How it works

Program the POS to take the dollar amount for the transaction using the token for the saved card.

Scenario	Merchant uses the POS to:
A customer wants to purchase goods using their saved card details.	Run a sale with the customer's details that they have saved in a previous transaction.

Payment sources: token

Sample request

Content-Type: application/json
Authorization: AuthToken {AuthTokenV2}
X-GP-Request-Id: {request_id}
X-GP-Version: 2021-04-08
X-GP-Api-Key: {API Key}
X-GP-Partner-App-Name: {Name of integrating application}
{
  "reference_id": "MER-41e40db1-02c8-4214-b2c8-1399aea79afa",
  "card": {
    "token": "xxXXXxXXxX"
  },
  "customer": {
    "billing_address": {
      "line1": "8200 Central Ave.",
      "postal_code": "94560"
    }
  },
  "payment": {
    "amount": "20.00",
    "currency_code": "840"
  },
  "transaction": {
    "country_code": "840",
    "ecommerce_indicator": "2",
    "processing_indicators": {
      "address_verification_service": true,
      "generate_receipt": true
    }
  }
}

Sample response

{
    "creditsale_id": "000000084347",
    "status": "approved",
    "approval_code": "108755",
    "avs_response": "full_match",
    "avs_response_description": "Match - Street Address, Match - Postal Code",
    "processor_response": "DEVELOPMENT APPROVAL",
    "card": {
        "masked_card_number": "476173XXXXXX0010",
        "expiry_month": "12",
        "expiry_year": "25",
        "type": "visa"
    },
    "payment": {
        "amount": "7.41",
        "currency_code": "840",
        "type": "credit"
    },
    "transaction": {
        "batch_amount": "40.44",
        "batch_number": "000060",
        "entry_type": "keyed",
        "language": "en-US"
    },
    "receipt": {
        "text": {
            "customer_receipt": "\nBatch #             000060\nTrans ID            000000084347\nOrder ID            MER-04ab7f85-3453-41\n                    a8-a794-ab176efa8a91\nTrans Type          Purchase\nDate/Time           2023-06-16 13:11:47\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       108755\n\nTotal Amount        USD$7.41\n\n          Approved - Thank You\n\n X____________________________________\n          Cardholder Signature\n\nBuyer agrees to pay total amount above\naccording to cardholder's agreement with\nissuer.\n\n         ****Customer Copy****",
            "merchant_receipt": "\nBatch #             000060\nTrans ID            000000084347\nOrder ID            MER-04ab7f85-3453-41\n                    a8-a794-ab176efa8a91\nTrans Type          Purchase\nDate/Time           2023-06-16 13:11:47\nCard Type           Visa\nCard Number         XXXXXXXXXXXX0010\nEntry Method        MANUAL\nApproval Code       108755\n\nTotal Amount        USD$7.41\n\n          Approved - Thank You\n\n X____________________________________\n          Cardholder Signature\n\nBuyer agrees to pay total amount above\naccording to cardholder's agreement with\nissuer.\n\n         ****Merchant Copy****"
        },
        "id": "84347",
        "attributes": {
            "authorization_agreement": "Buyer agrees to pay total amount above according to cardholder's agreement with issuer.",
            "copy_label_customer": "****Customer Copy****",
            "copy_label_merchant": "****Merchant Copy****",
            "verbiage": "Approved - Thank You"
        },
        "labeled_attributes": {
            "amount": {
                "label": "Total Amount",
                "value": "USD$7.41"
            },
            "approval_code": {
                "label": "Approval Code",
                "value": "108755"
            },
            "batch_number": {
                "label": "Batch #",
                "value": "000060"
            },
            "card_type": {
                "label": "Card Type",
                "value": "Visa"
            },
            "entry_method": {
                "label": "Entry Method",
                "value": "MANUAL"
            },
            "masked_card_number": {
                "label": "Card Number",
                "value": "XXXXXXXXXXXX0010"
            },
            "reference_id": {
                "label": "Order ID",
                "value": "MER-04ab7f85-3453-41a8-a794-ab176efa8a91"
            },
            "total_amount": {
                "label": "Total Amount",
                "value": "USD$7.41"
            },
            "transaction_datetime": {
                "label": "Date/Time",
                "value": "2023-06-16 13:11:47"
            },
            "transaction_id": {
                "label": "Trans ID",
                "value": "000000084347"
            },
            "transaction_type": {
                "label": "Trans Type",
                "value": "Purchase"
            }
        }
    },
    "links": [
        {
            "creditsale_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000084347",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retrieve a sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000084347",
                    "relation": "self",
                    "method": "PATCH",
                    "description": "Use this endpoint to update the amount or other values of a previous sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000084347/voids",
                    "relation": "void",
                    "method": "PUT",
                    "description": "Use this endpoint to void a previous sales transaction."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/000000084347/returns",
                    "relation": "return",
                    "method": "POST",
                    "description": "Use this endpoint to create a returns transaction associated with a previous sales transaction."
                }
            ]
        },
        {
            "reference_id": [
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/reference_id/MER-04ab7f85-3453-41a8-a794-ab176efa8a91",
                    "relation": "self",
                    "method": "GET",
                    "description": "Use this endpoint to retreive a previous sales transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/reference_id/MER-04ab7f85-3453-41a8-a794-ab176efa8a91",
                    "relation": "self",
                    "method": "PATCH",
                    "description": "Use this endpoint to update the amount or other values of a previous sales transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/reference_id/MER-04ab7f85-3453-41a8-a794-ab176efa8a91/voids",
                    "relation": "void",
                    "method": "PUT",
                    "description": "Use this endpoint to void a previous sales transaction using reference id."
                },
                {
                    "href": "https://api.pit.paygateway.com/transactions/creditsales/reference_id/MER-04ab7f85-3453-41a8-a794-ab176efa8a91/returns",
                    "relation": "return",
                    "method": "POST",
                    "description": "Use this endpoint to create a returns transaction associated with a previous sales using reference id."
                }
            ]
        }
    ],
    "reference_id": "MER-04ab7f85-3453-41a8-a794-ab176efa8a91"
}

Hosted Fields - Tokenization Guide | Global Payments