Authorize and Capture Transaction Flow

The authorize and capture transaction flow begins when a user submits credit card information through the Integrator user interface (UI), which posts directly to the Genius Payment Interface (GPI) to obtain a single-use token for PCI compliance. After the token is obtained, the capture phase is triggered through a Genius Payment Router (GPR). During the capture phase:

GPR sends a merchant capture request to GPI using the authorization token.
GPI receives confirmation and propagates the success response back through the system to complete the payment.

Authorize and Capture Transaction Flow Diagram

The following token interactions and operations are used for the authorize and capture transaction flow:

Step	Token Interaction	Path
1	(POST) Request One-Time Token	https://ecommerce.merchantware.net/v1/api/tokens
2	(POST) GPR Authorization Request	https://{gpr-url}/authorize-payments
3	(POST) Capture Payment Endpoint - Process Payment	https://{gpr-url}/process-payment

POST /v1/api/tokens

Summary

Use this endpoint to request a one-time token.

Request Parameters

In	Field Name	Type	Required	Description
body	`body`	PostOneTimeTokenRequestBody	Yes	The request body information

Response

Code	Description	Schema
200	Success Message: Ok	PostOneTimeTokenResponseBody

Code

Description

Schema

200

Success

Message: Ok

PostOneTimeTokenResponseBody

PostOneTimeTokenRequestBody

Field Name	Type	Required	Description
`merchantApiKey`	string	Yes	The Merchant API key required to generate a one-time token
`cardNumber`	string	Yes	The credit card number
`expirationmonth`	string	Yes	The credit card expiration month
`expirationyear`	string	Yes	The credit card expiration year
`cvv`	string	Yes	The Card Verification Value (CVV) number for the credit card
`cardHolder`	string	Yes	The credit card holder name
`streetaddress`	string	Yes	The credit card holder street address
`zipcode`	string	Yes	The credit card holder zip or postal code

Sample Request Body

{
   "merchantApiKey": "V1S0CCKS16LSPJL3",
   "cardNumber":"6011850288258637",
   "expirationmonth": "12",
   "expirationyear": "26",
   "cvv" : "123",
   "cardHolder": "John Doe",
   "streetaddress" : "1 Federal St",
   "zipcode": "02110"
}

PostOneTimeTokenResponseBody

Field Name	Type	Description
`token`	string	The token information
`currency`	string	The currency type
`created`	string (date/time)	The date and time the token was created
`expires`	string (date/time)	The date and time the token expires
`errors`	string	An error description, if applicable

Sample Response Body

{
    "token": "OTT_DDLQPMJSL6R7TUTXC43RT3OWLM84",
    "currency": "usd",
    "created": "2026-01-19T07:49:42.7800000Z",
    "expires": "2026-01-19T07:59:42.7800000Z",
    "errors": null
}

POST /authorize-payments

Summary

Use this endpoint for payment authorization.

Request Parameters

In	Field Name	Type	Required	Description
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company in which the menu will be created
header	`X-SITE-IDs`	string	Yes	The UID for the site in which the menu will be created
header	`AUTHORIZATION`	string	Yes	The token required to perform API calls for the company. For information on tokens, see Authentication.
body	`body`	PostAuthorizePaymentsRequestBody	Yes	The request body information

Responses

Code	Description	Schema
200	Success	PostAuthorizePaymentsResponseBody
400	Failure

PostAuthorizePaymentsRequestBody

Field Name	Type	Required	Description
`amount`	number	Yes	The authorization amount
`account_data`	string	Yes	The authorization data. Depends on the `account_data_type` field.
`account_data_type`	string	Yes	The authorization type. Possible values: `CardReferenceId` `OneTimeToken` `AuthTransactionId`
`order_number`	string	No*	The unique order number. *This field is required for FreedomPay when the amount is more than 0.
`business_date`	string	No	The business date in ISO-8601 format
`entry_method`	string	No	The entry method. For example, `App`.
`timeout`	number	No	Timeout in milliseconds
`card_nickname`	string	No	The nickname for the card
`name_on_card`	string	No	The name on the card
`email`	string	No	The customer email
`session_key`	string	No	The Hosted Payment Controls (HPC) bearer token received during in the request
`board_card`	boolean	No	If the value is `true`, save the card details for future payments

Sample Request Body

[
    {
        "reference_id": "981c8b22-dd4d-4f4d-8860-b18ffcf1e507",
        "amount": 22,
        "business_date": "2021-03-04T00:00:00.000Z",
        "account_data": "OTT_DDLQPMJSL6R7TUTXC43RT3OWLM84",
        "account_data_type": "OneTimeToken",
        "board_card": false,
        "timeout": 30,
        "terminal_id": 2523918973
    }
]

PostAuthorizePaymentsResponseBody

Field Name	Type	Description
`merchant_data`	merchant_data Object	The object containing the merchant information
`server_date_time`	string	The server date and time the record was created
`payment_methods`	payment_methods Array	The transaction information

Sample Response Body: Success

{
    "merchant_data": {
        "name": "Genius",
        "xenial_id": "genius",
        "id": "L7AYDTR5"
    },
    "server_date_time": "2026-01-19T07:55:09.769Z",
    "payment_methods": [
        {
            "transaction_data": {
                "id": "6618523328",
                "reference_id": "e528dbe4-b893-454a-8958-e5f452dcd98b",
                "amount": 6,
                "business_date": "2021-03-04T00:00:00.000Z",
                "terminal_id": 2523918973,
                "transaction_id": "6618523328",
                "account_data": "OTT_DDLQPMJSL6R7TUTXC43RT3OWLM84",
                "account_data_type": "OneTimeToken",
                "board_card": false,
                "status": "authorized",
                "error_description": "",
                "code": "00",
                "card_brand_name": "DISCOVER",
                "name_on_card": "John Doe",
                "masked_card_number": "************8637",
                "vendor": "Genius",
                "processor": "Genius",
                "avs_code": "",
                "cvv_code": "",
                "fraud_scoring": {
                    "external_reference": "JJC80469827S",
                    "recommendation": "Approve",
                    "score": "34",
                    "status": "Success"
                }
            }
        }
    ]
}

Sample Response Body: Failure

{
    "merchant_data": {
        "name": "Genius",
        "xenial_id": "genius",
        "id": "L7AYDTR5"
    },
    "server_date_time": "2026-01-19T07:58:04.603Z",
    "payment_methods": [
        {
            "transaction_data": {
                "id": "",
                "reference_id": "ca659069-586c-4b4f-ba84-eeffb2cf2612",
                "amount": 0,
                "business_date": "2021-03-04T00:00:00.000Z",
                "terminal_id": 2523918973,
                "transaction_id": "",
                "account_data": "OTT_TDYRJ6XEO7ZPC746WETEG3QU52HU",
                "account_data_type": "OneTimeToken",
                "board_card": false,
                "status": "authorize-failed",
                "error_description": 
"FAILED;99999;payment information not available",
                "code": "E0",
                "card_brand_name": "UNKNOWN",
                "name_on_card": "",
                "masked_card_number": "",
                "vendor": "Genius",
                "processor": "Genius",
                "avs_code": "",
                "cvv_code": ""
            }
        }
    ]
}

merchant_data Object

Field Name	Type	Description
`name`	string	The merchant name
`xenial_id`	string	The merchant identifier (ID) assigned by Genius
`id`	string	The merchant ID

payment_methods Array

Field Name	Type	Description
`transaction_data`	transaction_data Object	The object containing the transaction information

transaction_data Object

Field Name	Type	Description
`id`	string	The transaction identifier (ID)
`reference_id`	string	The transaction reference ID
`amount`	number	The transaction amount
`business_date`	string (date/time)	The transaction business date and time
`terminal_id`	string	The transaction terminal ID
`transaction_id`	string	The transaction ID
`account_data`	string	The authorization data
`account_data_type`	string	The authorization type
`board_card`	boolean	A flag that indicates whether to save credit card information for future transactions
`status`	string	The transaction status
`error_description`	string	The error description, if applicable
`code`	string	The transaction code
`card_brand_name`	string	The transaction credit card brand name
`name_on_card`	string	The name on the card
`masked_card_number`	string	The partial credit card number
`vendor`	string	The vendor name for the transaction
`processor`	string	The processor name for the transaction
`avs_code`	string	The Address Verification System (AVS) code
`cvv_code`	string	The Credit Verification Value (CVV) code
`fraud_scoring`	fraud_scoring Object	The object containing the fraud scoring information

fraud_scoring Object

Field Name	Type	Description
`external_reference`	string	The external reference identifier (ID)
`recommendation`	string	The fraud scoring recommendation. For example, `Approve`.
`score`	number	The fraud score number
`status`	string	The fraud scoring status. For example, `Success`.

POST /process-payment

Summary

Use this endpoint for payment processing.

Request Parameters

In	Field Name	Type	Required	Description
header	`X-COMPANY-ID`	string	Yes	The unique identifier (UID) for the company in which the menu will be created
header	`X-SITE-IDs`	string	Yes	The UID for the site in which the menu will be created
header	`AUTHORIZATION`	string	Yes	The token required to perform API calls for the company. For information on tokens, see Authentication.
body	`body`	PostProcessPaymentRequestBody	Yes	The request body information

Response

Code	Description	Schema
200	Success	PostProcessPaymentResponseBody

PostProcessPaymentRequestBody

Field Name	Type	Required	Description
`amount`	number	Yes	The payment amount
`reference_id`	string	Yes	The reference identifier (ID) from the payment
`account_data`	string	Yes	The data from the account where the payment is being performed. The value depends on the `account_data_type` field.
`account_data_type`	string	Yes	The authorization type. Possible values: `CardReferenceId` `OneTimeToken` `AuthTransactionId`
`auth_reference_id`	string	No	The reference ID for the authorized transaction related to current capture transaction
`authorized_amount`	number	No*	The authorized amount to be processed for the payment. *This field is required if `auth_reference_id` is not provided and is used for FreedomPay only.
`order_amount`	number	No	The total order amount
`tip_amount`	number	No	The tip amount
`order_id`	string	No	The order ID related to the payment being processed
`business_date`	string	No	The business date of the payment
`order_number`	string	No	The order number related to the payment being processed
`entry_method`	string	No	The entry method used for payment
`card_nickname`	string	No	The card nickname used for payment
`pos_local_time`	string (time)	No	The local time from the point of sale (POS) device when the request was performed
`pos_local_date`	string (date)	No	The local date from the POS device when the request was performed
`email`	string	No	The customer email
`timeout`	number	No	Timeout in milliseconds
`terminal_id`	string	No	The terminal ID from where the request was performed
`sync_request`	boolean	No	A flag that indicates whether the transaction will be synchronized

Sample Request Body

{
    "reference_id": "cd938b05-b2fc-4d05-abc8-13b80b5eadb5",
    "amount": 22,
    "order_id": "4444",
    "tip_amount": 1,
    "order_number": "4443",
    "auth_reference_id": ""
    "account_data": "6618523328",
    "account_data_type": "AuthTransactionId",
    "board_card": false,
    "entry_method": "App",
    "pos_local_time": "08:01:02",
    "pos_local_date": "2026-01-19",
    "terminal_id": "123",
    "timeout": 60,
    "sync_request": true
}

PostProcessPaymentResponseBody

Field Name	Type	Description
`server_date_time`	string	The server date and time the record was created
`merchant_data`	merchant_data Object	The object containing the merchant information
`transaction_data`	transaction_data Object	The object containing the transaction information

Sample Response Body

{
    "server_date_time": "2026-01-19T08:25:36.769Z",
    "merchant_data": {
        "name": "Genius",
        "xenial_id": "genius"
    },
    "transaction_data": {
        "id": "6618523741",
        "reference_id": "41e00489-04d3-4652-8a47-2df32df78423",
        "amount": 22,
        "order_amount": 22,
        "tip_amount": null,
        "order_number": "4443",
        "business_date": null,
        "store_number": null,
        "account_data": "6618523328",
        "account_data_type": "AuthTransactionId",
        "entry_method": "App",
        "pos_local_time": "08:21:53",
        "pos_local_date": "2026-01-19",
        "terminal_id": "123",
        "status": "paid",
        "error_description": "",
        "code": "00",
        "site_id": "686d239eb861285896b26ede",
        "company_id": "6127996c79b2660008ff150b",
        "server_time_stamp": "2026-01-19T08:21:53.456Z",
        "processor": "Genius",
        "vendor": "Genius",
        "auth": "OK9999"
    }
}

merchant_data Object

Field Name	Type	Description
`name`	string	The merchant name
`xenial_id`	string	The merchant identifier (ID) assigned by Genius

transaction_data Object

Field Name	Type	Description
`id`	string	The transaction identifier (ID)
`reference_id`	string	The transaction reference ID
`amount`	number	The transaction amount
`order_amount`	number	The total order amount
`tip_amount`	number	The tip amount
`order_number`	string	The order number related to the payment being processed
`business_date`	string (date/time)	The transaction business date and time
`store_number`	string	The store number
`account_data`	string	The authorization data
`account_data_type`	string	The authorization type
`entry_method`	string	The entry method used for payment
`pos_local_time`	string (time)	The local time from the point of sale (POS) device when the request was performed
`pos_local_date`	string (date)	The local date from the POS device when the request was performed
`terminal_id`	string	The transaction terminal ID
`status`	string	The transaction status
`error_description`	string	The error description, if applicable
`code`	string	The transaction code
`site_id`	string	The site ID for the transaction
`company_id`	string	The company ID for the transaction
`server_time_stamp`	string (date/time)	The server date and time the record was created
`processor`	string	The processor name for the transaction
`vendor`	string	The vendor name for the transaction
`auth`	string	The transaction authorization code

Authorize and Capture Transaction Flow

POST /v1/api/tokens

PostOneTimeTokenRequestBody

PostOneTimeTokenResponseBody

POST /authorize-payments

PostAuthorizePaymentsRequestBody

PostAuthorizePaymentsResponseBody

merchant_data Object

payment_methods Array

transaction_data Object

fraud_scoring Object

POST /process-payment

PostProcessPaymentRequestBody

PostProcessPaymentResponseBody

merchant_data Object

transaction_data Object

Search results