Set up payment extensions

Ask about this Page
Copy for LLM
View as Markdown

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 X-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_processorPOSTPerforms initialization steps on the payment provider.
connect_card_readerPOSTConnects to the credit reader.
payment_transaction/:transaction_idGETReturns payment intent. Only applies if the provider supports payment capture before collecting payment.
credit_available_refund/:processor_idGETReturns the available refund for the specified transaction.
capture_paymentPOSTReturns a payment intent.
collect_credit_paymentPOSTCollects the payment using a pin entry device (PED).
create_credit_refundPOSTApplies a credit refund.
cancel_credit_paymentPOSTCancels a credit payment request.

initialize_credit_processor

Request
FieldTypeDescriptionExample
processorStringThe credit processor to initialize."Custom"
X-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"
X-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
X-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.true
registration_codeStringDevice registration code."32423424224"
managing_agentStringDevice managing agent."Custom"
X-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, 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"
methodStringThe value that populates the Payment Method field in the Merchant Center."Adyen Credit Card"
verifySignatureBooleanSet as true if the customer must provide a signature. A true value triggers the capture_payment process.false
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"
X-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 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"
X-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_processPOSTProcesses 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"
amountObjectAmount object in cents.{"amount":"1220", "precision":"2", "currency":"USD"}
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"
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_walletPOSTPerforms initialization steps for the payment provider.
pay_walletPOSTSends a wallet payment request.
available_wallet_refundPOSTReturns the available wallet refund amount.
cancel_wallet_paymentPOSTSends a request to cancel the wallet.
log_cancel_walletPOSTLogs a wallet request to cancel the wallet.
refund_wallet_paymentPOSTSends 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."001"
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 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
X-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-123"
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 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/processPOSTPerforms pay on account operations as per the specified action.
payonaccountlogPOSTLogs 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 account."1220"
precisionStringPrecision level of the value."2"
currencyStringISO currency code."USD"
credit_limitObjectSpecify the amount, precision, and currency, 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", or "Update"
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 account."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 a 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, orUpdate"Create"
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 an amount of 10.00 dollars
amountStringValue to add to the account."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 Update"Create"
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 account."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