Payment extensions
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, gift 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 all endpoints are set up to receive data in JSON format. This means that your script or program should expect to receive data in the format of a JSON object, with properties and values that match the data being sent from InStore.
Configure all endpoints to verify the SHA256 hashed signature that InStore sends with each request. This signature is a security measure that ensures that 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 typically named
verification-signature
. - Use your own private key and the incoming request body to generate a SHA256 hash.
- 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 typically named
All requests and responses are JSON formatted.
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" |
verification_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" | |
verification_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 |
---|---|---|---|
verification_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. | "P400" | |
registration_code | String | Device registration_code. | "32423424224" | |
managing_agent | String | Device managing_agent. | "Custom" | |
verification_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 , Simulator | Simulator | |
processor_id | String | Identifier of the transaction that the payment provider returns. | 213121111 | |
last4 | String | Last four digits 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 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" | |
verification_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: | {...} similar to payment | |
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 |
verification_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 |
Gift card extension
Supported actions | Type | Description |
---|---|---|
storedvaluecard | POST | Creates a new gift card. |
storedvaluecard/:number | POST | Returns gift card information given the card number. |
storedvaluecard_process | POST | Process gift card operations, such as redeeming and loading, and updates the balance. |
storedvaluecard
Use the storedvaluecard
extension to create a new gift card.
Request
Field | Attributes | Type | Description | Example |
---|---|---|---|---|
type | String | Type of card, such as GiftCard , ReturnCard , or Promotional . | ReturnCard | |
balance | Object | Balance of the gift card in cents. | {amount:'1220',precision:2,currency:'USD'} | |
amount | String | Value to add to the gift card. | 1220 | |
precision | String | Precision level of the value. | 2 | |
currency | String | ISO currency code. | USD | |
status | String | Status of the gift card. | active | |
issuer | String | Issuer of the gift card. | My Store |
Response
Field | Attributes | Type | Description | Example |
---|---|---|---|---|
issuer | String | Issuer of the gift card. | My Store | |
number | String | Number of the gift card. | 4332423424242 | |
type | String | Type of card, such as GiftCard , ReturnCard , or Promotional . | ReturnCard | |
balance | Object | Balance of the gift card in cents. | {amount:'1220',precision:2,currency:'USD'} | |
amount | String | Value to add to the gift card. | 1220 | |
precision | String | Precision level of the value. | 2 | |
currency | String | ISO currency code. | USD | |
status | String | Status of the gift card. | active |
storedvaluecard/:number
Use the storedvaluecard/:number
extension to return a gift card information using the given gift card number.
Request
Field | Type | Description | Example |
---|---|---|---|
number | String | Number of the gift card. | 4332423424242 |
cartKey | String | Identifier of the Cart. | 3819232132 |
Response
Field | Attributes | Type | Description | Example |
---|---|---|---|---|
issuer | String | Issuer of the gift card. | My Store | |
number | String | Number of the gift card. | 4332423424242 | |
type | String | Type of card, such as GiftCard , ReturnCard , or Promotional . | ReturnCard | |
balance | Object | Balance of the gift card in cents. | {amount:'1220',precision:2,currency:'USD'} | |
amount | String | Value of the gift card. | 1220 | |
precision | String | Precision level of the value. | 2 | |
currency | String | ISO currency code. | USD | |
status | String | Status of the gift card. | active | |
result | String | Result of the request. | "Success" or "Failure" | |
errorCode | String | Error code if the request failed. | 00 | |
reason | String | Message if the request failed. | Error message | |
cartKey | String | Identifier of the Cart. | "3819232132" |
storedvaluecard_process
Use the storedvaluecard_process
extension to process gift card operations, such as redeeming and loading values, which updates the balance.
Request
Field | Type | Description | Example |
---|---|---|---|
location_id | String | Identifier of the store. | 001 |
session_id | String | Identifier of the transaction. | 4332423424242 |
action | String | Type of log entry, such as, Load or Redeem . | Redeem |
number | String | Number of the gift card. | 4332423424242 |
amount | Object | Object with the amount in cents. | {amount:'1220', precision:2, currency:'USD'} |
Response
Field | Attribtes | Type | Description | Example |
---|---|---|---|---|
issuer | String | Issuer of the gift card. | My Store | |
number | String | Number of the gift card. | 4332423424242 | |
type | String | Type of card, such as GiftCard , ReturnCard , or Promotional . | ReturnCard | |
balance | Object | Amount remaining on the gift card. | {amount:'1220',precision:2,currency:'USD'} | |
amount | String | Value to add to the gift card. | 1220 | |
precision | String | Precision level of the value. | 2 | |
currency | String | ISO currency code. | USD | |
status | String | Status of the gift card. | active | |
result | String | Result of the request. | "Success" or "Failure" | |
errorCode | String | Error code if the request failed. | 00 | |
reason | String | Message if the request failed. | Error message |
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' | POST | Sends a request to cancel the wallet. |
'log_cancel_wallet' | POST | Logs a wallet request to cancel the wallet. |
'refund_wallet' | 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. | { "location_id": location } |
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 gift card's value. | A private messaging/payment 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 |
---|---|---|---|
verification_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#> |
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 gift card's value. | A private messaging/payment 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 gift card. | 1220 | |
precision | String | Precision level of the value. | 2 | |
currency | String | ISO currency code. | USD | |
credit_limit | Object | Specify the amount, precision, and current, 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 , orUpdate | |
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 gift card. | 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 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 amount of 10.00 dollars | |
amount | String | Value to add to the gift card. | 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 gift card. | 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 |