Operation Definitions
Endpoints
The Process Payment, Cancel Payment, and Refund Payment endpoints are asynchronous, and only return a status message. For full results of the operation, send the reference_id value as a query parameter in a GET request to the Transaction Status endpoint.
The Payment Router API base path is https://xpr.xenial.com/.
POST /api/process-payment
Summary
The Process Payment operation submits a wallet identifier obtained at the point of sale (POS) that is used to pay for the transaction. For example, Paypal and Citcon provide in-app QR codes to identify the wallet. The QR codes are scanned at the POS, and the associated data is sent in the body of the Process Payment request. A successful Process Payment request sets the transaction-status property to payment-pending.
The Process Payment operation is asynchronous. The operation returns a status_code and message. If successful, the transaction status is set to payment-pending.
For the final results of the request, use the Transaction Status operation.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
header |
| string | Yes |
|
header |
| string | Yes | The previously created integrator token |
header |
| string | Yes | The unique company identifier provided by us |
header |
| string | Yes | The site identifier for the location performing the transaction |
body |
| Yes | The transaction information including the |
Responses
Code | Description |
|---|---|
200 | Success Message: Ok |
400 | Error Message: Bad Request |
401 | Error Message: Token Authentication Error |
403 | Error Message: Token Authentication Error |
406 | Error Message: Not Acceptable |
00 | Success |
01 | Pending |
C0 | Cancelled |
E0 | Error |
POST /api/cancel-payment
Summary
The Cancel Payment operation cancels a payment transaction if the funds were not yet withdrawn from the payment account.
The Cancel Payment operation is asynchronous. The operation returns a status_code and message. If successful, the transaction status is initially set to cancel-pending and then cancelled when complete.
For the final results of the request, use the Transaction Status operation.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
header |
| string | Yes |
|
header |
| string | Yes | The previously created integrator token |
header |
| string | Yes | The unique company identifier provided by us |
header |
| string | Yes | The site identifier for the location performing the transaction |
body |
| Yes | Includes the |
Responses
Code | Description |
|---|---|
202 | Success Message: Ok |
400 | Error Message: Bad Request |
401 | Error Message: Token Authentication Error |
403 | Error Message: Token Authentication Error |
406 | Error Message: Not Acceptable |
00 | Success |
01 | Pending |
C0 | Cancelled |
E0 | Error |
POST /api/refund-payment
Summary
The Refund Payment operation cancels a transaction and returns funds to the payment account.
The Refund Payment operation is asynchronous. The operation returns a status_code and message. If successful, the transaction status is initially set to refund-pending and then refunded when complete.
For the final results of the request, use the Transaction Status operation.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
header |
| string | Yes |
|
header |
| string | Yes | The previously created integrator token |
header |
| string | Yes | The unique company identifier provided by us |
header |
| string | Yes | The site identifier for the location performing the transaction |
body |
| Yes | Includes the |
Responses
Code | Description |
|---|---|
202 | Success Message: Ok |
400 | Error Message: Bad Request |
401 | Error Message: Token Authentication Error |
403 | Error Message: Token Authentication Error |
406 | Error Message: Not Acceptable |
00 | Success |
01 | Pending |
C0 | Cancelled |
E0 | Error |
GET /api/transaction-status
Summary
The Transaction Status operation returns the current status of a transaction identified by the reference_id specified in the query string of the request URL.
Request Parameters
In | Field Name | Type | Required | Description |
|---|---|---|---|---|
header |
| string | Yes |
|
header |
| string | Yes | The previously created integrator token |
header |
| string | Yes | The unique company identifier provided by us |
header |
| string | Yes | The site identifier for the location performing the transaction |
query |
| string | Yes | The unique, integrator-defined transaction identifier used to identify a specific transaction in requests to Payment Router API |
Responses
Code | Description | Schema |
|---|---|---|
200 | Transaction information and a status message. Possible statuses:
|
Data Models
ProcessPaymentRequestBody
Field Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | The unique identifier (UID) provided by the integrator Returned in the |
| number | No | The amount requested for payment |
| number | No | The amount of the order paid. This is useful for partial payments. |
| string | No | The UID for the order |
| number | No | |
| string | No | The order number |
| string | Yes | The QR code data obtained from the scanned QR code displayed on the mobile device of the guest |
| string | No | The account data type such as QR code |
| string | No | The order entry method such as |
| string | No | The local time for the point of sale (POS) |
| string | No | The local date for the POS |
| string | No | The customer's email address |
| string | No | The transaction status such as |
| string | No | The UID for the terminal |
| string | No |
CancelPaymentRequestBody
Field Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | The unique identifier (UID) provided by the integrator Returned in the |
| string | No | The reason for the cancelation |
RefundPaymentRequestBody
Field Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | A POS-generated identifier for the previous Process Payment transaction |
| string | Yes | The unique identifier (UID) provided by the integrator Returned in the |
| number | Yes | The amount to refund to the guest |
| number | Yes | The full amount of the original order |
| string | No | The partner-generated identifier for the previous payment transaction. To obtain the |
| string | No | The reason for the cancelation |
TransactionStatusResponseBody
Field Name | Type | Description |
|---|---|---|
| The merchant name and identifiers | |
| string | The local data and time for the server |
| The transaction identifiers and amounts |
merchant_data Object
Field Name | Type | Description |
|---|---|---|
| string | The name from the Portal subscription |
| string | The identifier (ID) from the Portal subscription |
| string | The identifier from the digital wallet service |
transaction_data Object
Field Name | Type | Description |
|---|---|---|
| string | The transaction identifier generated by our system |
| string | The unique identifier (UID) provided by the integrator |
| number | The amount requested for payment |
| number | |
| string | The order number |
| string | The business date of the transaction |
| string | The store number where the transaction was requested |
| string | The QR code data obtained from the scanned QR code displayed on the mobile device of the guest |
| string | The account data type such as QR code |
| string | The order entry method such as |
| string | The local time for the point of sale (POS) |
| string | The local date for the POS |
| string | The customer's email address |
| string | The UID for the terminal |
| string | The transaction status such as |
| string | Present only if applicable |
| string | The error message |
| string | The applicable response code |
Sample Code
Process Payment Request
{
"reference_id": "", // provided by integrator
"amount": 1.23, // amount requested for payment
"order_amount": 1.23, // amount of order paid,
// useful for partial payments
"order_id": "123456789",
"tip_amount": 1,
"order_number": "900001",
"account_data": "QR Data",
"account_data_type": "QR Code",
"entry_method": "Scan",
"pos_local_time": "local-time",
"pos_local_date": "local-date",
"email": "thing@stuff.com",
"status": "payment-pending",
"terminal_id": "123",
"timeout": 30
}Cancel Payment Request
{
"reference_id": ""
"reason": ""
} Refund Payment Request
{ "reference_id": "" "reason": "" } Transaction Status Response
Success Response Example
{
"merchant_data": {
//name from portal subscription
"name": "name",
//id from portal subscription
"xenial_id": "id",
//id from the digital wallet service
"id": "provider_merchant_id",
},
"server_date_time": "",
"transaction_data": {
//'transaction_id' generated by our system
"id": "transaction_id",
//integrator-generated unique identifier
//for the transaction set in the
//Process Payment request
"reference_id": "integrator-generated uid",
"amount": 1.23,
"tip_amount": 1.23,
"order_number": "",
"business_date": "",
"store_number": "",
"account_data": "",
"account_data_type": "",
"entry_method": "",
"pos_local_time": "",
"pos_local_date": "",
"email": "",
"terminal_id": "",
//see status list above
"status": "payment status",
//present only if a cancel is triggered
"cancellation_status": "cancelled",
//present only if applicable
"error_description": "Error Message",
//see code list above
"code": "code"
}
}No Status Response Example
{
"merchant_data": {
//name from portal subscription
"name": "name",
//id from portal subscription
"xenial_id": "id",
//id from the digital wallet service
"id": "provider_merchant_id"
},
"server_date_time": "",
"transaction_data": {
"status": "undefined"
"reference_id": "same value from the request"
}
}