Learn how to integrate with additional payment providers.
Payment extensions allow you to support additional payment providers that aren't integrated with InStore by default. Custom implementations can be integrated for credit cards, stored-value cards, digital wallet, and pay on account. Each custom payment extension needs to implement predefined InStore endpoints for that tender type. The InStore payment extension proxy sends requests to the URL that you preregister in the InStore Center with the results of the process executed in your in-store application.
Set up a custom payment extension
The specific details of setting up a custom extension and verifying the signature may vary depending on the programming language, framework, and server setup you are using.
To set up a custom payment extension, do the following:
-
Set up endpoints on your server to receive the custom payment extension data. You need to create a script or program that listens for incoming requests at a specific URL and supports all endpoints defined for the payment type of the particular extension. You can do this using a variety of programming languages and frameworks, depending on your server setup. InStore sends HTTP POST and GET requests to the URL you specify.
-
Make sure your endpoints can handle the request format used by each action. POST actions receive JSON-formatted request and response bodies. GET actions use route or query parameters, as documented for that action.
-
Configure all endpoints to verify the HMAC-SHA256 signature that InStore sends with each request. This signature is a security measure that ensures the data being sent to your endpoint is actually coming from InStore and has not been tampered with in transit.
-
To verify the signature, you'll need to perform the following steps:
- Extract the signature from the incoming proxy request headers. The header key for the signature is
X-Signature. - Compute an HMAC-SHA256 hash over the JSON-stringified request payload, using the shared verification key you configured for the extension in the InStore Center.
- Compare the generated hash to the signature included in the incoming request headers. If they match, the data has not been tampered with and can be safely processed by your endpoint.
- Once you've verified the signature, you can process the incoming data as needed. This may involve storing it in a database, triggering other actions in your system, or sending a response back to acknowledge receipt of the request.
- Extract the signature from the incoming proxy request headers. The header key for the signature is
The shared verification key is a symmetric secret, not an asymmetric private key. Both InStore and your extension must hold the same key.
Credit card extension
| Supported actions | Type | Description |
|---|---|---|
initialize_credit_processor | POST | Performs initialization steps on the payment provider. |
connect_card_reader | POST | Connects to the credit reader. |
payment_transaction/:transaction_id | GET | Returns payment intent. Only applies if the provider supports payment capture before collecting payment. |
credit_available_refund/:processor_id | GET | Returns the available refund for the specified transaction. |
capture_payment | POST | Returns a payment intent. |
collect_credit_payment | POST | Collects the payment using a pin entry device (PED). |
create_credit_refund | POST | Applies a credit refund. |
cancel_credit_payment | POST | Cancels a credit payment request. |
initialize_credit_processor
Request
| Field | Type | Description | Example |
|---|---|---|---|
processor | String | The credit processor to initialize. | "Custom" |
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" | |
error | String | Error message if the request failed. | "Error message" | |
data | Object | Data returned on the request. | {"captureEnabled": true, "simulated": false} | |
captureEnabled | Boolean | Indicates if the payment provider requires capture prior to payment collection. | true | |
simulated | Boolean | Indicates if the payment provider is using simulated test cards from InStore. | false |
connect_card_reader
Request
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
ped | Object | Details of the payment device to connect to. | {...} | |
status | String | Status of the device. | "Active" | |
name | String | Name of the device. | "Verifone P400" | |
type | String | Type of device. | "PED" | |
description | String | Description of the device. | "Frontdesk PED" | |
location | String | Identifier of the store. | "001" | |
brand | String | Brand of the device. | "Verifone" | |
model | String | Model of the device. | "P400" | |
shared | Boolean | Set to true if the device is shared. | true | |
registration_code | String | Device registration code. | "32423424224" | |
managing_agent | String | Device managing agent. | "Custom" | |
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" | |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" |
error | String | Error message if the request failed. | "Device Offline" |
capture_payment
Request
| Field | Type | Description | Example |
|---|---|---|---|
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" |
cartKey | String | Identifier of the Cart. | "3819232132" |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" | |
error | String | Error message if the request failed. | "Error message" | |
cartKey | String | Identifier of the Cart. | "010014175777" | |
data | Object | Contains the returned data about the request. | {...} | |
processor | String | Payment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator. | "Simulator" | |
processor_id | String | Identifier of the transaction that the payment provider returns. | "213121111" | |
last4 | String | Last four digits of the credit card number. | "4242" | |
brand | String | Brand of the credit card. | "visa" | |
account_type | String | Type of card account, such as credit or debit. | "credit" | |
application_preferred_name | String | Cardholder's name as displayed on their credit or debit card. | null | |
dedicated_file_name | String | Identifier used by the card issuer. | null | |
authorization_response_code | String | Code that indicates the status of the transaction request sent to the card issuer. | "3030" | |
application_cryptogram | String | Digital signature generated by the card’s embedded chip. | null | |
terminal_verification_results | String | A series of bits set by the PED for deciding how to respond to the request for payment. | null | |
transaction_status_information | String | Status of the transaction, which is returned by the card issuer. | null | |
status | String | Status of the payment, which is returned from the card issuer. | "requires_capture" |
collect_credit_payment
Request
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
saleId | String | Identifier of the session. | ||
testCard | String | Test card used in simulator mode, which is obtained from InStore. | ||
reference | String | InStore identifier of the transaction. | ||
amount | Object | Indicates the amount to collect for the payment. | ||
ped | Object | Contains details of the payment device to connect to. | {...} | |
status | String | Status of the device. | "Active" | |
name | String | Name of the device. | "Verifone P400" | |
type | String | Type of device. | "PED" | |
description | String | Description of the device. | "Frontdesk PED" | |
location | String | Identifier of the store. | "001" | |
brand | String | Brand of the device. | "Verifone" | |
model | String | Model of the device. | "P400" | |
shared | Boolean | Set to true if the device is shared. | true | |
registration_code | String | Device registration code. | "32423424224" | |
managing_agent | String | Device managing agent. | "Custom" | |
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" | |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" | |
cartKey | String | Identifier of the Cart. | "010014175777" |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" | |
error | String | Error message if the request failed. | "Error message" | |
cartKey | String | Identifier of the Cart. | "010014175777" | |
data | Object | Contains the data returned about the request. | {...} | |
processor | String | Payment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator. | "Simulator" | |
processor_id | String | Identifier of the transaction that the payment provider returns. | "213121111" | |
last4 | String | Last four digits of the credit card number. | "4242" | |
brand | String | Brand of the credit card. | "visa" | |
account_type | String | Type of card account, such as credit or debit. | "credit" | |
method | String | The value that populates the Payment Method field in the Merchant Center. | "Adyen Credit Card" | |
verifySignature | Boolean | Set as true if the customer must provide a signature. A true value triggers the capture_payment process. | false | |
application_preferred_name | String | Cardholder's name as displayed on their credit or debit card. | null | |
dedicated_file_name | String | Identifier used by the card issuer. | null | |
authorization_response_code | String | Code that indicates the status of the transaction request sent to the card issuer. | "3030" | |
application_cryptogram | String | Digital signature generated by the card’s embedded chip. | null | |
terminal_verification_results | String | A series of bits set by the PED for deciding how to respond to the request for payment. | null | |
transaction_status_information | String | Status of the transaction, which is returned by the card issuer. | null | |
status | String | Status of the payment, which is returned by the card issuer. | "requires_capture" |
create_credit_refund
Request
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
saleId | String | Identifier of the session. | "34234324234" | |
last4 | String | Last four digits of the card number. | "4242" | |
reference | String | InStore identifier of the transaction. | "3434534453453" | |
amount | String | Refund amount. | ||
currency | String | ISO currency code. | "USD" | |
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" | |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" | |
error | String | Error message if the request failed. | "Error message" | |
data | Object | Data returned on the request. As below: | {...} | |
processor | String | Payment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator. | "Simulator" | |
processor_id | String | Identifier of the transaction that the payment provider returns. | "213121111" | |
last4 | String | Last four digits of the credit card number. | "4242" | |
brand | String | Brand of the credit card. | "visa" | |
account_type | String | Type of card account, such as credit or debit. | "credit" | |
application_preferred_name | String | Cardholder's name as displayed on their credit or debit card. | null | |
dedicated_file_name | String | Identifier used by the card issuer. | null | |
authorization_response_code | String | Code that indicates the status of the transaction request sent to the card issuer. | "3030" | |
application_cryptogram | String | Digital signature generated by the card’s embedded chip. | null | |
terminal_verification_results | String | A series of bits set by the PED for deciding how to respond to the request for payment. | null | |
transaction_status_information | String | Status of the transaction, which is returned by the card issuer. | null | |
status | String | Status of the action. | "approved" |
cancel_credit_payment
Request
| Field | Type | Description | Example |
|---|---|---|---|
processor_id | String | Identifier of the transaction, which the payment provider returns. | "213121111" |
last4 | String | Last four digits of the credit card number. | "4242" |
brand | String | Brand of the credit card. | "visa" |
account_type | String | Type of card account, such as credit or debit. | "credit" |
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" | |
error | String | Error message if the request failed. | "Error message" | |
data | Object | Data returned on the request. As below: | {...} | |
processor | String | Payment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator. | Simulator | |
processor_id | String | Identifier of the transaction that the payment provider returns. | 213121111 | |
last4 | String | Last four digits of the credit card number. | 4242 | |
brand | String | Brand of the credit card. | visa | |
account_type | String | Type of card account, such as credit or debit. | credit | |
application_preferred_name | String | Cardholder's name as displayed on their credit or debit card. | null | |
dedicated_file_name | String | Identifier used by the card issuer. | null | |
authorization_response_code | String | Code that indicates the status of the transaction request sent to the card issuer. | 3030 | |
application_cryptogram | String | Digital signature generated by the card’s embedded chip. | null | |
terminal_verification_results | String | A series of bits set by the PED for deciding how to respond to the request for payment. | null | |
transaction_status_information | String | Status of the transaction, which is returned by the card issuer. | null | |
status | String | Status of action. | approved |
Stored-value card extension
| Supported actions | Type | Description |
|---|---|---|
storedvaluecard | POST | Creates a new stored-value card. |
storedvaluecard/:number | POST | Returns stored-value card information given the card number. |
storedvaluecard_process | POST | Processes stored-value card operations, such as redeeming, loading, and canceling, and updates the balance. |
storedvaluelog/:number | GET | Returns the transaction log for a stored-value card. |
The stored-value card actions use two request patterns. InStore sends
storedvaluecard, storedvaluecard/:number, and storedvaluecard_process through an asynchronous webhook envelope by POSTing the wrapped payload to the URL configured for your extension. Your extension must respond synchronously with an acknowledgment and then deliver the final result asynchronously by calling the callbackUrl included in the envelope. storedvaluelog/:number is a GET request and is documented separately below.Webhook envelope and authentication
Each POST request that InStore sends to your stored-value card extension uses the following envelope. The fields your extension should parse for business logic live inside
payload; everything else is delivery metadata.| Field | Type | Description |
|---|---|---|
payload_url | String | The full URL that InStore resolved for this request, including the action path (for example storedvaluecard_process). |
payload | Object | The business payload for the action. The field tables for each action below describe this object. |
verification_signature | String | HMAC-SHA256 of JSON.stringify(payload), computed with your shared verification key. Duplicated in the X-Signature header. |
tenant_id | String | Identifier of the InStore tenant that sent the request. |
requestId | String | Unique identifier for this request. Echo it back when you call callbackUrl. |
callbackUrl | String | URL your extension must POST the final result to once the operation has completed. |
statusUrl | String | URL your extension can POST progress updates to while the operation is running. |
Each request also includes the following headers:
| Header | Description |
|---|---|
X-Signature | HMAC-SHA256 of JSON.stringify(payload) using the shared verification key you configured for this extension. Compare against your own computed hash to verify authenticity. |
X-API-Key | Optional. Present when the tenant has a webhook API key configured. Use it as an additional authentication check. |
x-correlation-id | Correlation identifier for distributed tracing. Log it and propagate it on any downstream calls. |
The signature algorithm is HMAC-SHA256 with a shared secret, not a digital signature with an asymmetric private key. Both sides must hold the same verification key.
storedvaluecard
Use the
storedvaluecard action to create a new stored-value card.Request payload
| Field | Attributes | Type | Required | Description | Example |
|---|---|---|---|---|---|
requestId | String | Yes | Unique identifier for this request. | "req-9a8b..." | |
locationId | String | Yes | User-defined location identifier (for example "01" or "LondonStore"). | "LondonStore" | |
workstationId | String | No | Identifier of the workstation that originated the request. | "POS-03" | |
type | String | Yes | Type of card. One of GiftCard, ReturnCard, or Promotional. | "ReturnCard" | |
status | String | Yes | Status of the stored-value card. One of Active or Inactive. | "Active" | |
balance | Object | Yes | Balance of the stored-value card. | {"amount":1220,"precision":2,"currency":"USD"} | |
amount | Number | Yes | Monetary value in minor units, such as cents or pence. | 1220 | |
precision | Number | Yes | Number of digits after the decimal point. | 2 | |
currency | String | Yes | ISO-4217 currency code. | "USD" | |
issuer | String | No | Issuer of the stored-value card. | "My Store" | |
cvc | String | No | Card verification code, if the processor uses one. | "123" | |
customer_id | String | No | Identifier of the customer the card is being issued to. | "cust-44" |
Synchronous response
Your extension should respond with an acknowledgment containing the
requestId. The final operation result is delivered asynchronously to the callbackUrl from the envelope.| Field | Type | Description | Example |
|---|---|---|---|
requestId | String | Echo of the incoming requestId. | "req-9a8b..." |
storedvaluecard/:number
Use the
storedvaluecard/:number action to return stored-value card information for the given card number.Request payload
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
requestId | String | Yes | Unique identifier for this request. | "req-9a8b..." |
locationId | String | Yes | User-defined location identifier. | "LondonStore" |
workstationId | String | No | Identifier of the workstation that originated the request. | "POS-03" |
number | String | Yes | Number of the stored-value card to look up. | "4332423424242" |
cartKey | String | Yes | Identifier of the Cart the lookup is associated with. | "3819232132" |
pin | String | No | Card PIN, if the processor uses one. | "1234" |
accounts | Array of InjectedStoredValueAccount | No | Pre-resolved account data for batch lookups. See Pre-loaded accounts. | [{"number":"4332...","pin":"1234"}] |
Synchronous response
| Field | Type | Description | Example |
|---|---|---|---|
requestId | String | Echo of the incoming requestId. | "req-9a8b..." |
storedvaluecard_process
Use the
storedvaluecard_process action to process stored-value card operations. Three actions are supported: Load, Redeem, and Cancel. Load and Redeem share the same request shape; Cancel uses a different shape because it references a prior transaction instead of an amount.Load and Redeem
Request payload
| Field | Attributes | Type | Required | Description | Example |
|---|---|---|---|---|---|
requestId | String | Yes | Unique identifier for this request. | "req-9a8b..." | |
locationId | String | Yes | User-defined location identifier. | "LondonStore" | |
workstationId | String | No | Identifier of the workstation that originated the request. | "POS-03" | |
action | String | Yes | Operation to perform. One of Load or Redeem. | "Redeem" | |
number | String | Yes | Number of the stored-value card to operate on. | "4332423424242" | |
amount | Object | Yes | Amount to load or redeem. | {"amount":1220,"precision":2,"currency":"USD"} | |
amount | Number | Yes | Monetary value in minor units, such as cents or pence. | 1220 | |
precision | Number | Yes | Number of digits after the decimal point. | 2 | |
currency | String | Yes | ISO-4217 currency code. | "USD" | |
session_id | String | Yes | Identifier of the checkout session the operation belongs to. | "session-7c..." | |
reference | String | Yes | Reference that ties this operation back to the originating transaction or Cart. | "order-2025-0001" | |
cvc | String | No | Card verification code, if the processor uses one. | "123" | |
accounts | Array | No | Pre-resolved account data for batch operations. See Pre-loaded accounts. | [{"number":"4332...","paymentProcessorId":"..."}] |
Cancel
Use
action: "Cancel" to reverse a previously completed stored-value card operation. The request references the external identifiers returned by the processor on the original operation; no new amount is supplied.Request payload
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
requestId | String | Yes | Unique identifier for this request. | "req-9a8b..." |
locationId | String | Yes | User-defined location identifier. | "LondonStore" |
workstationId | String | No | Identifier of the workstation that originated the request. | "POS-03" |
action | String | Yes | Must be "Cancel". | "Cancel" |
number | String | Yes | Number of the stored-value card being cancelled. | "4332423424242" |
external_transaction_id | String | Yes | External transaction identifier returned by the processor on the original Load or Redeem. | "tx-8827..." |
external_payment_id | String | Yes | External payment identifier returned by the processor on the original operation. | "pay-2210..." |
Synchronous response
Applies to
Load, Redeem, and Cancel:| Field | Type | Description | Example |
|---|---|---|---|
requestId | String | Echo of the incoming requestId. | "req-9a8b..." |
storedvaluelog/:number
Use the
storedvaluelog/:number action to return the transaction log for a stored-value card. Unlike the other stored-value card actions this one is a GET. The parameters are sent as query string values rather than in a JSON body, and the envelope headers (X-Signature, X-API-Key, x-correlation-id) still apply.Request query parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
requestId | String | Yes | Unique identifier for this request. | "req-9a8b..." |
locationId | String | Yes | User-defined location identifier. | "LondonStore" |
workstationId | String | No | Identifier of the workstation that originated the request. | "POS-03" |
Synchronous response
| Field | Type | Description | Example |
|---|---|---|---|
requestId | String | Echo of the incoming requestId. | "req-9a8b..." |
Pre-loaded accounts mode
For multi-card checkouts or when the POS already holds resolved card data, InStore can send pre-loaded accounts on
storedvaluecard_process requests. InStore can also send pre-loaded accounts on storedvaluecard/:number requests. When the accounts array is present, InStore groups accounts by paymentProcessorId and sends one request per group, so a single processor only ever receives the accounts routed to it.InjectedStoredValueAccount
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
number | String | Yes | Stored-value card number. | "4332423424242" |
pin | String | No | Card PIN, if the processor uses one. | "1234" |
balance | Object | No | Pre-resolved balance, using the same { amount, precision, currency } shape. | {"amount":1220,"precision":2,"currency":"USD"} |
type | String | No | Card type. One of GiftCard, ReturnCard, or Promotional. | "GiftCard" |
paymentProcessorId | String | No | InStore identifier used to route this account to a specific processor in multi-processor tenants. Stripped from the payload before it is forwarded to your extension. |
When
accounts is supplied on storedvaluecard_process, the synchronous response uses a results array so the POS can correlate each processor's requestId:{
"results": [
{ "requestId": "req-9a8b...", "paymentProcessorId": "664f..." },
{ "requestId": "req-9a8c..." }
]
}
Processor configuration
The behavior of your stored-value card extension is shaped by the configuration fields set on the
PaymentProcessor in the InStore Center. These fields tell the POS which stored-value flows to run against your extension. Keep them in mind when deciding which endpoints your implementation must support.| Field | Values | Description |
|---|---|---|
cardNumberMethod | Manual, Injected, Requested | How card numbers are obtained. Requested means the POS will call the storedvaluecard/:number action to fetch card data from your extension; Injected means the POS sends pre-loaded account data inline using accounts. |
cardBalanceMethod | Injected, Requested | Whether balances are requested from the extension or sent inline by the POS. |
accountMethod | Injected, Requested | Whether the full account record is requested from the extension or sent inline. |
enableFields | Any subset of CardNumber, Pin, Balance, CardType | The fields the POS will prompt for and include on requests to your extension. |
url | String | The base URL of your extension. Every action path is appended to this URL. |
apiKey | String | The shared verification key used to compute and verify the HMAC-SHA256 X-Signature. |
timeout | Number (ms) | Maximum time InStore will wait for your extension to acknowledge a request. |
Digital wallet extension
| Supported actions | Type | Description |
|---|---|---|
initialize_wallet | POST | Performs initialization steps for the payment provider. |
pay_wallet | POST | Sends a wallet payment request. |
available_wallet_refund | POST | Returns the available wallet refund amount. |
cancel_wallet_payment | POST | Sends a request to cancel the wallet. |
log_cancel_wallet | POST | Logs a wallet request to cancel the wallet. |
refund_wallet_payment | POST | Sends a refund wallet request. |
initialize_wallet
Use the
initialize_wallet extension to perform initialization steps for the payment provider.Request
| Field | Type | Description | Example |
|---|---|---|---|
location_id | String | Identifier of the store location. | "001" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" |
error | String | Error message if the request failed. | Error message |
code | String | Code that represents an error. | 00 |
pay_wallet
Use the
pay_wallet extension to send a wallet payment request.Request
| Field | Type | Description | Example |
|---|---|---|---|
barcode | String | Barcode from the wallet provider customer. | "123456789012345678901000" |
currency | String | ISO currency code. | "USD" |
total | Integer | Total payment amount. Assumes a precision level of 2. | 16960 |
pos_local_time | String | Local time on the POS terminal. | "2024-01-24 12:37:54" |
tip | Integer | Tip amount. Assumes a precision level of 2. | 300 |
note | String | Note that describes the transaction. | "payment" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
transaction_id | String | Identifier of the transaction, which the wallet provider returns. | "242342342424" |
total | String | Total amount of the request. | "1050" |
tip | String | Tip amount. | "1" |
subtotal | String | Subtotal of the transaction. | "1150" |
merchant_id | String | Identifier of the merchant. | "634100700040000" |
terminal_id | String | Identifier of the terminal. | "00000011" |
method | String | Method for delivering the stored-value card's value. | "A private messaging platform" |
pos_local_time | String | Local time on the POS terminal. | "2024-01-23 12:35:05" |
result | String | Result of the request. | "Success" or "Failure" |
code | String | Result code. | "00" |
error_message | String | Error message if the request failed. | "Error message" |
available_wallet_refund
Use the
available_wallet_refund extension to return the available wallet refund amount.Request
| Field | Type | Description | Example |
|---|---|---|---|
transaction_id | String | Identifier of the transaction from the wallet provider. | "242342342424" |
pos_local_time | String | Local time on the POS terminal. | "2024-01-23 12:35:05" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" |
error | String | Error message if the request failed. | "Error message" |
code | String | Result code. | "00" |
cancel_wallet_payment
Use the
cancel_wallet_payment extension to send a request to cancel the wallet.Request
| Field | Type | Description | Example |
|---|---|---|---|
X-Signature | String | Verification signature for authorization. | "asdibasdy7128e71" |
tenant_id | String | Identifier of the tenant. | "b312-c121-3f45-ab34" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" |
error | String | Error message if the request failed. | "Error message" |
code | String | Result code. | "00" |
log_cancel_wallet
Use the
log_cancel_wallet extension to log a wallet cancelation request.Request
| Field | Type | Description | Example |
|---|---|---|---|
barcode | String | Wallet barcode used for the transaction. | "barcode-123" |
total | String | Total amount of the transaction. | "465500" |
tip | Integer | Tip amount. | 1 |
currency | String | ISO currency code. | "USD" |
reference | String | Reference to the sales transaction. | "123456" |
response_code | String | Result code. | "00" |
transaction_id | String | Identifier of the transaction from the wallet provider. | "242342342424" |
pos_local_time | String | Local time in the POS terminal. | "2024-01-23 12:35:05" |
error_message | String | Error message if the request failed. | "Error message" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
result | String | The result of the request. | "Success" or "Failure" |
error | String | Error message if the request failed. | "Error message" |
code | String | Result code. |
refund_wallet_payment
Use the
refund_wallet_payment extension to send a refund wallet request.Request
| Field | Type | Description | Example |
|---|---|---|---|
transaction_id | String | Identifier of the transaction from the wallet provider. | "242342342424" |
pos_local_time | String | Local time of the POS terminal. | "2024-01-23 12:35:05" |
note | String | Note to describe transaction. | "refund" |
Response
| Field | Type | Description | Example |
|---|---|---|---|
result | String | Result of the request. | "Success" or "Failure" |
error_message | String | Error message if the request failed. | "Error message" |
code | String | Result code. | "00" |
transaction_id | String | Identifier of the transaction from the wallet provider. | "242342342424" |
pos_local_time | String | Local time on the POS terminal. | "2024-01-23 12:35:05" |
merchant_id | String | Identifier of the merchant. | "634100700040000" |
terminal_id | String | Identifier of the terminal. | "00000011" |
method | String | Method for delivering the stored-value card's value. | "A private messaging platform" |
original_transaction_id | String | Identifier of the original transaction. | "1000000525" |
original_reference | String | Reference identifier of the original transaction. | "REF1234" |
Pay on account (POA) extension
| Supported actions | Type | Description |
|---|---|---|
payonaccount/process | POST | Performs pay on account operations as per the specified action. |
payonaccountlog | POST | Logs the pay on account operation. |
payonaccountlog/ | GET | Returns logs for a particular account number. |
payonaccount/process
Use the
payonaccount/process extension to create a new POA account, add credit to an account, query account details, or update the account.Request
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
action | String | Operation to perform, which is one of the following: Create, Credit, Inquiry, or Update. | "Update" | |
account_number | String | Account number. | "2342342342" | |
company_name | String | Company name. | "My Store" | |
authorized_user_ids | String array | List of authorized user identifiers. | ["234234", "987786"] | |
balance | Object | Provide the amount, precision, and currency. | {"amount":"1000", "precision":"2", "currency":"USD"} | |
amount | String | Value to add to the account. | "1220" | |
precision | String | Precision level of the value. | "2" | |
currency | String | ISO currency code. | "USD" | |
credit_limit | Object | Specify the amount, precision, and currency, only for the Create action. | {"amount":"50000", "precision":"2", "currency":"USD"} | |
amount | String | Value of the credit limit of the account. | "50000" | |
precision | String | Precision level of the value. | "2" | |
currency | String | ISO currency code. | "USD" |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
action | String | Indicates operation performed. | "Create", "Credit", "Inquiry", or "Update" | |
account_number | String | Account number. | "2342342342" | |
company_name | String | Company name. | "My Store" | |
authorized_user_ids | String array | List of authorized user identifiers for the create action. | ["234234", "987786"] | |
authorized_user_id | String | Identifier of the authorized user who performed the operation. | "234234" | |
balance | Object | Contains details of the account balance. | {"amount":"1000", "precision":"2", "currency":"USD"} indicates a balance of 10.00 dollars | |
amount | String | Value to add to the account. | "1220" | |
precision | String | Precision level of the value. | "2" | |
currency | String | ISO currency code. | "USD" | |
credit_limit | Object | Contains the details of the credit limit when a Create action was performed. | {"amount":"50000", "precision":"2", "currency":"USD"} indicates a credit limit of 500.00 dollars | |
amount | String | Value of the credit limit of the account. | "50000" | |
precision | String | Precision level of the value. | "2" | |
currency | String | ISO currency code. | "USD" | |
status | String | Status of the action, which is either approved or declined. | "approved" |
payonaccountlog
Use the
payonaccountlog extension to log POA actions.Request
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
action | String | Indicates which operation to perform, which is one of the following: Create, Credit,Inquiry, orUpdate | "Create" | |
account_number | String | Account number. | "2342342342" | |
company_name | String | Company name. | "My Store" | |
authorized_user_id | String | Identifier of the authorized user who is performing the action. | "234234" | |
amount | Object | Contains the details about the account balance. | {"amount":"1000", "precision":"2", "currency":"USD"} indicates an amount of 10.00 dollars | |
amount | String | Value to add to the account. | "1220" | |
precision | String | Precision level of the value. | "2" | |
currency | String | ISO currency code. | "USD" | |
session_id | String | Identifier of the transaction. | qe2304982020948209840 | |
order_id | String | Identifier of the order. | 0024242 | |
status | String | Status of the action, which is either approved or declined. | approved |
Response
| Field | Attributes | Type | Description | Example |
|---|---|---|---|---|
action | String | Indicates which action was performed, which is one of the following: Create, Credit, Inquiry, or Update | "Create" | |
account_number | String | Account number. | "2342342342" | |
company_name | String | Company name. | "My Store" | |
authorized_user_id | String | Identifier of the authorized user who performed the action. | "234234" | |
amount | Object | Contains details about the account balance. | {"amount":"1000", "precision":"2", "currency":"USD"} indicates an amount of 10.00 dollars. | |
amount | String | Value to add to the account. | "1220" | |
precision | String | Precision level of the value. | "2" | |
currency | String | ISO currency code. | "USD" | |
session_id | String | Identifier of the transaction. | qe2304982020948209840 | |
order_id | String | Identifier of the order. | 0024242 | |
status | String | Status of the action, which is either approved or declined. | approved |