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:

  1. 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.

  2. 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.

  3. 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.

  4. To verify the signature, you'll need to perform the following steps:

    1. Extract the signature from the incoming proxy request headers. The header key for the signature is typically named verification-signature.
    2. Use your own private key and the incoming request body to generate a SHA256 hash.
    3. 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.
    4. 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.

All requests and responses are JSON formatted.

Credit card extension

Supported actionsTypeDescription
'initialize_credit_processor'POSTPerforms initialization steps on the payment provider.
'connect_card_reader'POSTConnects to the credit reader.
'payment_transaction/:transaction_id'GETReturns payment intent. Only applies if the provider supports payment capture before collecting payment.
'credit_available_refund/:processor_id'GETReturns the available refund for the specified transaction.
'capture_payment'POSTReturns a payment intent.
'collect_credit_payment'POSTCollects the payment using a pin entry device (PED).
'create_credit_refund'POSTApplies a credit refund.
'cancel_credit_payment'POSTCancels a credit payment request.

initialize_credit_processor

Request

FieldTypeDescriptionExample
processorStringThe credit processor to initialize."Custom"
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"

Response

FieldAttributesTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
dataObjectData returned on the request.{captureEnabled: true, simulated: false}
captureEnabledBooleanIndicates if the payment provider requires capture prior to payment collection.true
simulatedBooleanIndicates if the payment provider is using simulated test cards from InStore.false

connect_card_reader

Request

FieldAttributesTypeDescriptionExample
pedObjectDetails of the payment device to connect to.{...}
statusStringStatus of the device."Active"
nameStringName of the device."Verifone P400"
typeStringType of device."PED"
descriptionStringDescription of the device."Frontdesk PED"
locationStringIdentifier of the store."001"
brandStringBrand of the device."Verifone"
modelStringModel of the device."P400"
sharedBooleanSet to true if the device is shared.true
registration_codeStringDevice registration_code."32423424224"
managing_agentStringDevice managing_agent."Custom"
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"

Response

FieldTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Device Offline

capture_payment

Request

FieldTypeDescriptionExample
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"
cartKeyStringIdentifier of the Cart."3819232132"

Response

FieldAttributesTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
cartKeyStringIdentifier of the Cart."010014175777"
dataObjectContains the returned data about the request.{...}
processorStringPayment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator.Simulator
processor_idStringIdentifier of the transaction that the payment provider returns.213121111
last4StringLast four digits of the credit card number.4242
brandStringBrand of the credit card.visa
account_typeStringType of card account, such as credit or debit.credit
application_preferred_nameStringCardholder's name as displayed on their credit or debit card.null
dedicated_file_nameStringIdentifier used by the card issuer.null
authorization_response_codeStringCode that indicates the status of the transaction request sent to the card issuer.3030
application_cryptogramStringDigital signature generated by the card’s embedded chip.null
terminal_verification_resultsStringA series of bits set by the PED for deciding how to respond to the request for payment.null
transaction_status_informationStringStatus of the transaction, which is returned by the card issuer.null
statusStringStatus of the payment, which is returned from the card issuer.requires_capture

collect_credit_payment

Request

FieldAttributesTypeDescriptionExample
saleIdStringIdentifier of the session.
testCardStringTest card used in simulator mode, which is obtained from InStore.
referenceStringInStore identifier of the transaction.
amountObjectIndicates the amount to collect for the payment.
pedObjectContains details of the payment device to connect to.{...}
statusStringStatus of the device."Active"
nameStringName of the device."Verifone P400"
typeStringType of device."PED"
descriptionStringDescription of the device."Frontdesk PED"
locationStringIdentifier of the store."001"
brandStringBrand of the device."Verifone"
modelStringModel of the device."P400"
sharedBooleanSet to true if the device is shared."P400"
registration_codeStringDevice registration_code."32423424224"
managing_agentStringDevice managing_agent."Custom"
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"
cartKeyStringIdentifier of the Cart."010014175777"

Response

FieldAttributesTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
cartKeyStringIdentifier of the Cart."010014175777"
dataObjectContains the data returned about the request.{...}
processorStringPayment provider, which is one of the following: Adyen, Stripe, Custom, SimulatorSimulator
processor_idStringIdentifier of the transaction that the payment provider returns.213121111
last4StringLast four digits the credit card number.4242
brandStringBrand of the credit card.visa
account_typeStringType of card account, such as, credit or debit.credit
application_preferred_nameStringCardholder's name as displayed on their credit or debit card.null
dedicated_file_nameStringIdentifier used by the card issuer.null
authorization_response_codeStringCode that indicates the status of the transaction request sent to the card issuer.3030
application_cryptogramStringDigital signature generated by the card’s embedded chip.null
terminal_verification_resultsStringA series of bits set by the PED for deciding how to respond to the request for payment.null
transaction_status_informationStringStatus of the transaction, which is returned by the card issuer.null
statusStringStatus of the payment, which is returned by the card issuer.requires_capture

create_credit_refund

Request

FieldAttributesTypeDescriptionExample
saleIdStringIdentifier of the session."34234324234"
last4StringLast four digits of the card number."4242"
referenceStringInStore identifier of the transaction."3434534453453"
amountStringRefund amount.
currencyStringISO currency code."USD"
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"

Response

FieldAttributesTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
dataObjectData returned on the request. As below:{...} similar to payment
processorStringPayment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator.Simulator
processor_idStringIdentifier of the transaction that the payment provider returns.213121111
last4StringLast four digits of the credit card number.4242
brandStringBrand of the credit card.visa
account_typeStringType of card account, such as credit or debit.credit
application_preferred_nameStringCardholder's name as displayed on their credit or debit card.null
dedicated_file_nameStringIdentifier used by the card issuer.null
authorization_response_codeStringCode that indicates the status of the transaction request sent to the card issuer.3030
application_cryptogramStringDigital signature generated by the card’s embedded chip.null
terminal_verification_resultsStringA series of bits set by the PED for deciding how to respond to the request for payment.null
transaction_status_informationStringStatus of the transaction, which is returned by the card issuer.null
statusStringStatus of the action.approved

cancel_credit_payment

Request

FieldTypeDescriptionExample
processor_idStringIdentifier of the transaction, which the payment provider returns.213121111
last4StringLast four digits of the credit card number.4242
brandStringBrand of the credit card.visa
account_typeStringType of card account, such as credit or debit.credit
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"

Response

FieldAttributesTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
dataObjectData returned on the request. As below:{...}
processorStringPayment provider, which is one of the following: Adyen, Stripe, Custom, or Simulator.Simulator
processor_idStringIdentifier of the transaction that the payment provider returns.213121111
last4StringLast four digits of the credit card number.4242
brandStringBrand of the credit card.visa
account_typeStringType of card account, such as credit or debit.credit
application_preferred_nameStringCardholder's name as displayed on their credit or debit card.null
dedicated_file_nameStringIdentifier used by the card issuer.null
authorization_response_codeStringCode that indicates the status of the transaction request sent to the card issuer.3030
application_cryptogramStringDigital signature generated by the card’s embedded chip.null
terminal_verification_resultsStringA series of bits set by the PED for deciding how to respond to the request for payment.null
transaction_status_informationStringStatus of the transaction, which is returned by the card issuer.null
statusStringStatus of action.approved

Gift card extension

Supported actionsTypeDescription
storedvaluecardPOSTCreates a new gift card.
storedvaluecard/:numberPOSTReturns gift card information given the card number.
storedvaluecard_processPOSTProcess gift card operations, such as redeeming and loading, and updates the balance.

storedvaluecard

Use the storedvaluecard extension to create a new gift card.

Request

FieldAttributesTypeDescriptionExample
typeStringType of card, such as GiftCard, ReturnCard, or Promotional.ReturnCard
balanceObjectBalance of the gift card in cents.{amount:'1220',precision:2,currency:'USD'}
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
statusStringStatus of the gift card.active
issuerStringIssuer of the gift card.My Store

Response

FieldAttributesTypeDescriptionExample
issuerStringIssuer of the gift card.My Store
numberStringNumber of the gift card.4332423424242
typeStringType of card, such as GiftCard, ReturnCard, or Promotional.ReturnCard
balanceObjectBalance of the gift card in cents.{amount:'1220',precision:2,currency:'USD'}
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
statusStringStatus 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

FieldTypeDescriptionExample
numberStringNumber of the gift card.4332423424242
cartKeyStringIdentifier of the Cart.3819232132

Response

FieldAttributesTypeDescriptionExample
issuerStringIssuer of the gift card.My Store
numberStringNumber of the gift card.4332423424242
typeStringType of card, such as GiftCard, ReturnCard, or Promotional.ReturnCard
balanceObjectBalance of the gift card in cents.{amount:'1220',precision:2,currency:'USD'}
amountStringValue of the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
statusStringStatus of the gift card.active
resultStringResult of the request."Success" or "Failure"
errorCodeStringError code if the request failed.00
reasonStringMessage if the request failed.Error message
cartKeyStringIdentifier 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

FieldTypeDescriptionExample
location_idStringIdentifier of the store.001
session_idStringIdentifier of the transaction.4332423424242
actionStringType of log entry, such as, Load or Redeem.Redeem
numberStringNumber of the gift card.4332423424242
amountObjectObject with the amount in cents.{amount:'1220', precision:2, currency:'USD'}

Response

FieldAttribtesTypeDescriptionExample
issuerStringIssuer of the gift card.My Store
numberStringNumber of the gift card.4332423424242
typeStringType of card, such as GiftCard, ReturnCard, or Promotional.ReturnCard
balanceObjectAmount remaining on the gift card.{amount:'1220',precision:2,currency:'USD'}
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
statusStringStatus of the gift card.active
resultStringResult of the request."Success" or "Failure"
errorCodeStringError code if the request failed.00
reasonStringMessage if the request failed.Error message

Digital wallet extension

Supported actionsTypeDescription
'initialize_wallet'POSTPerforms initialization steps for the payment provider.
'pay_wallet'POSTSends a wallet payment request.
'available_wallet_refund'POSTReturns the available wallet refund amount.
'cancel_wallet'POSTSends a request to cancel the wallet.
'log_cancel_wallet'POSTLogs a wallet request to cancel the wallet.
'refund_wallet'POSTSends a refund wallet request.

initialize_wallet

Use the initialize_wallet extension to perform initialization steps for the payment provider.

Request

FieldTypeDescriptionExample
location_idStringIdentifier of the store location.{ "location_id": location }

Response

FieldTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
codeStringCode that represents an error.00

pay_wallet

Use the pay_wallet extension to send a wallet payment request.

Request

FieldTypeDescriptionExample
barcodeStringBarcode from the wallet provider customer.123456789012345678901000
currencyStringISO currency code.USD
totalIntegerTotal payment amount. Assumes a precision level of 2.16960
pos_local_timeStringLocal time on the POS terminal.2024-01-24 12:37:54
tipIntegerTip amount. Assumes a precision level of 2.300
noteStringNote that describes the transaction.payment

Response

FieldTypeDescriptionExample
transaction_idStringIdentifier of the transaction, which the wallet provider returns.242342342424
totalStringTotal amount of the request.1050
tipStringTip amount.1
subtotalStringSubtotal of the transaction.1150
merchant_idStringIdentifier of the merchant.634100700040000
terminal_idStringIdentifier of the terminal.00000011
methodStringMethod for delivering the gift card's value.A private messaging/payment platform
pos_local_timeStringLocal time on the POS terminal.2024-01-23 12:35:05
resultStringResult of the request."Success" or "Failure"
codeStringResult code.00
error_messageStringError message if the request failed.Error message

available_wallet_refund

Use the available_wallet_refund extension to return the available wallet refund amount.

Request

FieldTypeDescriptionExample
transaction_idStringIdentifier of the transaction from the wallet provider.242342342424
pos_local_timeStringLocal time on the POS terminal.2024-01-23 12:35:05

Response

FieldTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
codeStringResult code.00

cancel_wallet_payment

Use the cancel_wallet_payment extension to send a request to cancel the wallet.

Request

FieldTypeDescriptionExample
verification_signatureStringVerification signature for authorization."asdibasdy7128e71"
tenant_idStringIdentifier of the tenant."b312-c121- 3f45-ab34"

Response

FieldTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
codeStringResult code.00

log_cancel_wallet

Use the log_cancel_wallet extension to log a wallet cancelation request.

Request

FieldTypeDescriptionExample
barcodeStringWallet barcode used for the transaction.<barcode#>
totalStringTotal amount of the transaction.465500
tipIntegerTip amount.1
currencyStringISO currency code.USD
referenceStringReference to the sales transaction.123456
response_codeStringResult code.00
transaction_idStringIdentifier of the transaction from the wallet provider.242342342424
pos_local_timeStringLocal time in the POS terminal.2024-01-23 12:35:05
error_messageStringError message if the request failed.Error message

Response

FieldTypeDescriptionExample
resultStringThe result of the request."Success" or "Failure"
errorStringError message if the request failed.Error message
codeStringResult code.

refund_wallet_payment

Use the refund_wallet_payment extension to send a refund wallet request.

Request

FieldTypeDescriptionExample
transaction_idStringIdentifier of the transaction from the wallet provider.242342342424
pos_local_timeStringLocal time of the POS terminal.2024-01-23 12:35:05
noteStringNote to describe transaction.refund

Response

FieldTypeDescriptionExample
resultStringResult of the request."Success" or "Failure"
error_messageStringError message if the request failed.Error message
codeStringResult code.00
transaction_idStringIdentifier of the transaction from the wallet provider.242342342424
pos_local_timeStringLocal time on the POS terminal.2024-01-23 12:35:05
merchant_idStringIdentifier of the merchant.634100700040000
terminal_idStringIdentifier of the terminal.00000011
methodStringMethod for delivering the gift card's value.A private messaging/payment platform
original_transaction_idStringIdentifier of the original transaction.1000000525
original_referenceStringReference identifier of the original transaction.REF1234

Pay on account (POA) extension

Supported actionsTypeDescription
'payonaccount/process'POSTPerforms pay on account operations as per the specified action.
'payonaccountlog'POSTLogs the pay on account operation.
'payonaccountlog/'GETReturns 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

FieldAttributesTypeDescriptionExample
actionStringOperation to perform, which is one of the following: Create, Credit, Inquiry, or Update.Update
account_numberStringAccount number.2342342342
company_nameStringCompany name.My Store
authorized_user_idsString arrayList of authorized user identifiers.['234234','987786']
balanceObjectProvide the amount, precision, and currency.{amount:'1000' precision:2 currency='USD'}
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
credit_limitObjectSpecify the amount, precision, and current, only for the create action.{amount:'50000' precision:2 currency='USD'}
amountStringValue of the credit limit of the account.50000
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD

Response

FieldAttributesTypeDescriptionExample
actionStringIndicates operation performed.Create, Credit,Inquiry, orUpdate
account_numberStringAccount number.2342342342
company_nameStringCompany name.My Store
authorized_user_idsString arrayList of authorized user identifiers for the create action.['234234','987786']
authorized_user_idStringIdentifier of the authorized user who performed the operation.'234234'
balanceObjectContains details of the account balance.{amount:'1000' precision:2 currency='USD'} indicates a balance of 10.00 dollars
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
credit_limitObjectContains 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`
amountStringValue of the credit limit of the account.50000
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
statusStringStatus of the action, which is either approved or declined.approved

payonaccountlog

Use the payonaccountlog extension to log POA actions.

Request

FieldAttributesTypeDescriptionExample
actionStringIndicates which operation to perform, which is one of the following: Create, Credit,Inquiry, orUpdateCreate
account_numberStringAccount number.2342342342
company_nameStringCompany name.My Store
authorized_user_idStringIdentifier of the authorized user who is performing the action.'234234'
amountObjectContains the details about the account balance.{amount:'1000' precision:2 currency='USD'} indicates amount of 10.00 dollars
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
session_idStringIdentifier of the transaction.qe2304982020948209840
order_idStringIdentifier of the order.0024242
statusStringStatus of the action, which is either approved or declined.approved

Response

FieldAttributesTypeDescriptionExample
actionStringIndicates which action was performed, which is one of the following: Create, Credit, Inquiry, or UpdateCreate
account_numberStringAccount number.2342342342
company_nameStringCompany name.My Store
authorized_user_idStringIdentifier of the authorized user who performed the action.234234
amountObjectContains details about the account balance.{amount:'1000' precision:2 currency='USD'} indicates an amount of 10.00 dollars.
amountStringValue to add to the gift card.1220
precisionStringPrecision level of the value.2
currencyStringISO currency code.USD
session_idStringIdentifier of the transaction.qe2304982020948209840
order_idStringIdentifier of the order.0024242
statusStringStatus of the action, which is either approved or declined.approved