Sale Transaction Flow
The sale transaction flow demonstrates a single-phase payment process where a user submits credit card information through the Genius Payment Interface (GPI) at merchantware.net to obtain a single-use token for PCI compliance. After the token is received:
The Integrator initiates payment by sending a process payment request through the Genius Payment Router (GPR).
GPR sends a merchant sale request to GPI that simultaneously authorizes and captures the funds in one transaction.
Sale Transaction Flow Diagram
 |
The following token interactions and operations are used for the sale transaction flow:
Step | Token Interaction | Path |
|---|---|---|
1 | ||
2 |
POST /v1/api/tokens
Summary
Use this endpoint to request a one-time token.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
body |
| Yes | The request body information |
Response
Code | Description | Schema |
|---|---|---|
200 | Success Message: Ok |
PostOneTimeTokenRequestBody
Field Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | The Merchant API key required to generate a one-time token |
| string | Yes | The credit card number |
| string | Yes | The credit card expiration month |
| string | Yes | The credit card expiration year |
| string | Yes | The Card Verification Value (CVV) number for the credit card |
| string | Yes | The credit card holder name |
| string | Yes | The credit card holder street address |
| 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 |
|---|---|---|
| string | The token information |
| string | The currency type |
| string (date/time) | The date and time the token was created |
| string (date/time) | The date and time the token expires |
| 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 /process-payment
Summary
Use this endpoint for payment processing.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
header |
| string | Yes | The unique identifier (UID) for the company in which the menu will be created |
header |
| string | Yes | The UID for the site in which the menu will be created |
header |
| string | Yes | The token required to perform API calls for the company. For information on tokens, see Authentication. |
body |
| Yes | The request body information |
Response
Code | Description | Schema |
|---|---|---|
200 | Success |
PostProcessPaymentRequestBody
Field Name | Type | Required | Description |
|---|---|---|---|
| number | Yes | The payment amount |
| string | Yes | The reference identifier (ID) from the payment |
| string | Yes | The data from the account where the payment is being performed. The value depends on the |
| string | Yes | The authorization type. Possible values:
|
| string | No | The reference ID for the authorized transaction related to current capture transaction |
| number | No* | The authorized amount to be processed for the payment. *This field is required if |
| number | No | The total order amount |
| number | No | The tip amount |
| string | No | The order ID related to the payment being processed |
| string | No | The business date of the payment |
| string | No | The order number related to the payment being processed |
| string | No | The entry method used for payment |
| string | No | The card nickname used for payment |
| string (time) | No | The local time from the point of sale (POS) device when the request was performed |
| string (date) | No | The local date from the POS device when the request was performed |
| string | No | The customer email |
| number | No | Timeout in milliseconds |
| string | No | The terminal ID from where the request was performed |
| boolean | No | A flag that indicates whether the transaction will be synchronized |
Sample Request Body
{
"reference_id": "b741edda-561f-4f0e-9943-ecd58e1bab7e",
"amount": 2,
"order_id": "5207d4cb-5fd8-4cfa-99ac-3dd8640f90db",
"order_number": "4444",
"account_data": "OTT_ETWURVEB5RISK1KBSSFXUIKVXPUL",
"account_data_type": "OneTimeToken",
"board_card": false,
"entry_method": "App",
"pos_local_time": "13:29:20",
"pos_local_date": "2026-01-22",
"email": "email@email.com",
"terminal_id": "123",
"timeout": 60,
"sync_request": true
}PostProcessPaymentResponseBody
Field Name | Type | Description |
|---|---|---|
| string | The server date and time the record was created |
| The object containing the merchant information | |
| 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 |
|---|---|---|
| string | The merchant name |
| string | The merchant identifier (ID) assigned by Genius |
transaction_data Object
Field Name | Type | Description |
|---|---|---|
| string | The transaction identifier (ID) |
| string | The transaction reference ID |
| number | The transaction amount |
| number | The total order amount |
| number | The tip amount |
| string | The order number related to the payment being processed |
| string (date/time) | The transaction business date and time |
| string | The store number |
| string | The authorization data |
| string | The authorization type |
| string | The entry method used for payment |
| string (time) | The local time from the point of sale (POS) device when the request was performed |
| string (date) | The local date from the POS device when the request was performed |
| string | The transaction terminal ID |
| string | The transaction status |
| string | The error description, if applicable |
| string | The transaction code |
| string | The site ID for the transaction |
| string | The company ID for the transaction |
| string (date/time) | The server date and time the record was created |
| string | The processor name for the transaction |
| string | The vendor name for the transaction |
| string | The transaction authorization code |