VTEX Developer Portal

Integrating inStore to a new payment acquirer

This article aims to explain how the inStore app configures AppLinking for payment and payment-reversal actions with the acquirers' apps.

Setting fields

All acquirers must have:

Field name

Type

Description

acquirerProtocol

string

The AppLinking protocol, that is, the payment app scheme. Ex: stone, cielo-lio, cappta.

scheme

string

The scheme to which the payment app's' Intent will respond. The default value is instore.

autoConfirm

boolean

The default value is True. Tells the app that it doesn't need to ask the user for any further permission to complete the action.

acquirerId

string

Affiliation ID of the acquirer which is registered in VTEX Payments module. Ex: <stone_code>, <sitef_storeId>.

If necessary, inStore can send additional information. Example with the sub-acquirer Cappta:

Field name

Type

Description

authKey

string

For example, <cappta_authKey>.

authPassword

string

For example, <cappta_authPassword>.

administrativePassword

string

Default password. For example, cappta.

cnpj

string

Company ID number.

📘

To create any extra configuration, you need to send an email to the inStore team ([email protected]) informing the additional information the app needs to complete the transaction. With that, we will create a form on the Payments module so that customers can configure their acquirer.

Sending URI and response URI for each action

Action: payment or payment-reversal (refund a previous payment).

  • URI pattern that is sent by AppLinking:
<acquirerProtocol>://<action>?<params>
  • Default URI received by AppLinking:
instore://<action>?<response_params>

Sample sending URI for each action

Example for the payment action

Payment context that is used to mount the URI (to make it easier to read):

{
  acquirerProtocol: "super-acquirer",
  action: "payment",
  acquirerId: "954090369",
  installmentType: 2, // 1: the interest for each installment is applied by the bank or by the credit card; 2: the store is responsible for interest on installments
  installments: 3,
  paymentId: "1093019888",
  paymentType: "debit",  // may also be "credit"
  amount: 10, // payment apps usually expect the amount in cents (10 cents, in this example)
  installmentsInterestRate: "1%" // if the payment has no interest rate, it should not be on mobileLinkingUrl
  transactionId: "1093019039",
  scheme: "instore",
  urlCallback: "instore://payment",
  autoConfirm: "True",
  paymentSystem: 44,
  paymentSystemName: "Venda Direta Debito",
  paymentGroupName: "debitDirectSalePaymentGroup",
  sellerName: "instoreqa",
  payerEmail: '[email protected]', // Customer's e-mail
  payerIdentification: '12345678909', // Customer's document
  mobileLinkingUrl: "super-acquirer://payment?acquirerId=954090369&paymentId=1093019888&paymentType=debit&amount=10&installments=3&transactionId=1093019039&autoConfirm=True&scheme=instore&urlCallback=instore://payment"
}

Final URI that the payment app will receive to perform the payment action with the context of the above example:

super-acquirer://payment?acquirerProtocol=super-acquirer&action=payment&acquirerId=954090369&installmentType=2&installments=3&paymentId=1093019888&paymentType=debit&amount=10&installmentsInterestRate=1%&transactionId=1093019039&paymentSystem=44&paymentSystemName=Venda%20Direta%20Debito&paymentGroupName=debitDirectSalePaymentGroup&sellerName=instoreqa&payerIdentification=12345678909&payerEmail=customeremail%40gmail.com&scheme=instore&urlCallback=instore://payment&autoConfirm=True

With the values present in this URI, it will be possible to reimburse this payment.

Example for the payment-reversal action (refund):

Refund context used to assemble the URI (in order to make it easier to read):

{
  acquirerProtocol: "super-acquirer",
  action: "payment-reversal",
  acquirerAuthorizationCode: "86273634-3a05-4f0a-a430-f55ed3f21eab", // identifies the payment transaction
  acquirerId: "954090369",
  transactionId: "1093019039",
  paymentId: "1093019888",
  acquirerTid: "1093019888",
  administrativeCode: "11010103033", // This ammount must be received from the payment and is saved in VTEX PCI Gateway.
  autoConfirm: "True",
  sellerName: "instoreqa",
  scheme: "instore",
  urlCallback: "instore://payment-reversal",
  mobileLinkingUrl: "super-acquirer://payment-reversal?acquirerAuthorizationCode=86273634-3a05-4f0a-a430-f55ed3f21eab&acquirerId=954090369&paymentId=1093019888&transactionId=1093019039&autoConfirm=True&scheme=instore&urlCallback=instore://payment-reversal"
}

Final URI that the payment app will receive to perform the refund action with the context of the above example:

super-acquirer://payment-reversal?acquirerAuthorizationCode=86273634-3a05-4f0a-a430-f55ed3f21eab&acquirerId=954090369&transactionId=1093019039&paymentId=1093019888&acquirerTid=1093019888&administrativeCode=11010103033&sellerName=instoreqa&autoConfirm=True&scheme=instore&urlCallback=instore://payment-reversal

🚧

Not all parameters will be used by all payment acquirers/apps. Example: transactionId. This parameter is the ID of a transaction in VTEX that identifies all payments of a complete order on VTEX PCI Gateway. A transaction can contain multiple payments, such as when an order is paid with multiple credit or debit cards.

Examples of response URIs for each action

Example for the payment action

URI:

Success: instore://payment?responsecode=0&<response_params>
Failed:  instore://payment?responsecode=110&reason=card+refused+by+acquirer&paymentId=<value_of_the_sender_URI>

Response Parameters:

Field name

Type

Description

scheme

string

instore

action

string

`payment

paymentId

string

Payment identification in VTEX

cardBrandName

string

Brand name, such as mastercard, visa, etc.

firstDigits

string

Card BIN / IIN (first six digits)

lastDigits

string

Card last four digits

acquirerName

string

Name of the acquirer (optional)

tid

string

Transaction identification code required to perform a refund action

acquirerAuthorizationCode

string

Transaction authorization code generated by the acquirer

nsu

string

Unique sequential number that identifies the operation

merchantReceipt

string

Text of the receipt for the establishment. Must be in the URI

customerReceipt

string

Text of the receipt for the client. Must be in the URI

responsecode

integer

0 means success; values greater than 0 mean acquirer error codes, in which case the reason parameter will be an error message

reason

string

On success, the value is empty; in case of error, it contains the error message

success

boolean

Generated by the app given the value of responsecode

- Example for the payment-reversal action (refund):

URI:

Success: instore://payment-reversal?responsecode=0&<response_params>
Failed:  instore://payment-reversal?responsecode=110&reason=card+refused+by+acquirer&paymentId=<id_sent_previously>

Response parameters:

Field name

Type

Description

scheme

string

instore

action

string

payment-reversal

paymentId

string

Ex: 1093019888 - to identify which payment was refunded

paymentAcquirerAuthorizationCode

string

Authorization code that was used for the refund action (tid)

acquirerAuthorizationCode

string

Transaction authorization code generated by the acquirer

merchantReceipt

string

Text of the receipt for the merchant. Must be in the URI

customerReceipt

string

Text of the receipt for the client. Must be in the URI

responsecode

integer

0 means "success"; values greater than 0 mean acquirer error codes, in which case the reason parameter will be an error message

reason

string

On success, the value is empty; in case of error, it contains the error message

success

boolean

Generated by the app given the value of responsecode

Setting up inStore connector in VTEX Payments module

For the integration to work, the customer must set up the inStore connector on the Payments module (our payment backend). In this connector, the customer must choose in the field Acquirer which acquirer or app will receive the payment. This registration must contain all the information necessary for the acquirer to carry out the transaction. Example: Acquirer Id, Token, etc.).

AppLinking integration doesn't include other dependencies, since communication between the inStore application and the payment application happens with specific URIs containing all the configuration and payment parameters required for the action.

🚧

On Android, all communication must happen with a new Intent. This means that you should not send the response as a callback from the initial Intent call. Instead, send a new Intent to the inStore application with the previous response.

To configure the inStore connector, follow the steps below:

  1. Access the Payments module.
  2. Access Settings.
  3. On the Gateway Affiliations tab, click the + button.
  4. Click the InStore connector.
  5. In the Acquirer field, select the acquirer which will receive the payment.
  6. Fill in the other setting fields of the connector according to the information passed by the acquirer (Type of installment, Acquirer Id, Extra Configurations, etc).

Learn more

Updated 3 months ago


Integrating inStore to a new payment acquirer


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.