Merchant Purchase

Setup in Sandbox/Production

For each environment:1. Create an account at Stark Bank.2. Create asynchronous Webhook subscriptions to receive update Events. Register an URL using the POST Webhook route to receive Events about the following resources:  2.1 Merchant Purchase: Creation and updates of Merchant Purchase

Creating Merchant Purchases

In this section, we will demonstrate how to create a Merchant Purchase via API to initiate charges for your customers.The process involves creating a Merchant Session and then creating a Merchant Purchase.The first step in the integration is creating a session. Sessions are essential for defining key purchase parameters, such as funding type, expiration, amount, and more.

Secondly, you can create a purchase from the UUID generated in the session through a public route, meaning this transaction cannot be saved in your backend.Note: the UUID serves as a unique key that allows us to associate the purchase your client is creating directly with your merchant account.

Creating Merchant Purchases with 3DS challenge

In this section, we will demonstrate how to create a card acquiring purchase via API using 3DS. 3DS is a protocol designed to enhance security for online credit and debit card transactions.The first step to create a merchant purchase with 3DS is to create a Merchant Session, like in the previous section, but the field 'challengeMode' must be set 'enabled'.

Secondly, you can create a purchase from the UUID generated in the session through a public route, like in the previous section. This transaction cannot also be saved in your backend.To create a merchant purchase with 3DS protocol it is necessary to fill the fields: 'billingCity', 'billingCountryCode', 'billingStateCode', 'billingStreetLine1', 'billingStreetLine2', 'billingZipCode', 'holderEmail', 'holderPhone'.It is also necessary to send the 'metadata' object and this object must contain this fields: 'userAgent', 'userIp' and 'language'.

Creating Zero Dollar Merchant Purchases

In this section, we will demonstrate how to create a zero dollar purchase via API. This resource is particullary usefull to check if the card is valid and if the cardholder has enough funds to make a purchase.The first step in the integration is creating a session, like in the previous section. But now, the filed 'allowedInstallments' must contain just one option with 'totalAmount' equals to '0' and 'count' equals to '1', like in the example below.

Secondly, you can create a purchase from the UUID generated in the session through a public route, like in the previous section. This transaction cannot also be saved in your backend.To create a zero dollar merchant purchase, it is only necessary set the field 'amount' to '0'.

Creating Recurrent Merchant Purchases

In this section, we will demonstrate how to create a merchant purchase via API using cardOnFile to initiate recurrent charges for your customers.For this integration, it is necessary to already have an approved purchase with this card. After the purchase is approved, it is generated an entity called Merchant Card and you can use it for recurrent purchases.The only field you need from the Merchant Card is it's id. You can check it consulting an approved Merchant Purchase or using the endpoint to list the Merchant Cards.

Consulting Merchant Purchase

Is it possible to retrieve an merchant purchase by its ID or even list them using parameters as limit, after, before to filter the results, as shown in the example below:

Consulting Merchant Installments

Is it possible to retrieve a Merchant Installment by its ID or even list them using parameters as limit, after, before to filter the results, as shown in the example below:

Canceling Merchant Purchase

In this section, we will demonstrate how to cancel a Merchant Purchase via API.To cancel a Merchant Purchase, it's status has to be approved and it's only possible to set the amount to 0. This action cancels the authorization.While the cancelation still in process, the purchase status will remain as approved.

Partially reversing Merchant Purchase

In this section, we will demonstrate how to partially reverse a Merchant Purchase via API. Partial reversals are only allowed one day after the purchase confirmation.To reverse a Merchant Purchase, it's status has to be confirmed. This action debits the difference and reverses the purchase.While the reversal still in process, the purchase status will remain as confirmed. After the partial reversal is completed, the status will also remain as confirmed.

Fully reversing Merchant Purchase

In this section, we will demonstrate how to fully reverse a Merchant Purchase via API.To reverse a Merchant Purchase, it's status has to be confirmed. This action debits the difference and reverses the purchase.While the reversal still in process, the purchase status will remain as confirmed. After the total reversal is completed, the status will be changed to voided.