Merchant advancement

Simulate merchant advancement

Create or simulate a merchant advancement request. To trigger a simulated advancement request, you must include confirmAdvancement=false in the query. If you specify true, the advancement request becomes an actual request, not a simulation.<br>

The endpoint enables a merchant to simulate an advancement scenario in order to validate whether or not there is enough balance in the account, as well as how much tax is anticipated. Since a simulated advancement is not a real advancement, it is not processed.

A merchant advancement is sometimes called a prepayment of receivables. You arrange to have a financial institution make regular deposits into your account equal to what you expect to receive in the future from credit card sales in installments or post-dated checks and bills. The financial institution deducts its fee before it puts the money in your account. You pay back each deposit when you receive payment from your customers. This is a way of covering business expenses in the short term. It's a cheaper alternative to a loan.<br>

<b>Note</b>:

  • If the merchant is the head merchant (also called a centralizer), the advanced amount is given to the head merchant instead of individual branch merchants, this is designed for better manageability.
  • If the commercial establishment is not registered as a headquarter or a branch in the current marketplace, the advancement is for a single commercial establishment.
  • The merchant must have sufficient balance in the account for the specified date range of the advancement.

This endpoint generates a Merchant advancement request created event.

post/v1/marketplaces/{marketplaceId}/merchants/{merchantId}/advancements

Request

  • Base URL
    https://sandbox.pismolabs.io/merchants
  • URL
    https://sandbox.pismolabs.io/merchants/v1/marketplaces/{marketplaceId}/merchants/{merchantId}/advancements
  • Auth
    none declared. Required headers: Authorization

Path parameters

marketplaceIdinteger required

Marketplace ID

merchantIdinteger required

Merchant ID

Query parameters

confirmAdvancementboolean

When set to true, it means you are sending an actual advancement request (confirmed advancement); otherwise, it is a simulated advancement. The default value is false.

Flag that indicates whether this is an effective advancement or just a simulation. The default value is false.

Headers

Authorizationstring required

Authorization token

Example:<your_token>

Request body

begin_datestring date required

Used for searching merchant advancement requests. This is the start date of your search range.

request_datestring date required

Date for payment of the advancement (YYYY-MM-DD). Must be greater than or equal to today, where "today" is evaluated in the merchant program's resolved timezone. The organization's timezone is used as fallback.

amountnumber float required

Net amount to be paid in advance

currency_codestring

Represents the currency with an ISO-4217 alphabetic or numeric (3 characters) string. For example, you represent Brazilian real with either BRL or 986. If you don't provide this code, the system uses the currency from the merchant program.

real_time_settlementboolean required

If true, the transaction is settled real-time; that is, at the exact moment. Default is false

end_datestring date

Used for searching merchant advancement requests. This is the end date of your search range

campaign_advancement_feenumber float

Campaign advancement fee to be applied to the current advancement request. It replaces the advancement fee set for the merchant in the request

campaign_discount_ratenumber float

Campaign discount rate to be applied to all merchants in the current advancement request

Example request

{
  "currency_code": "986"
}

Response

OK

simulation_idstring

A unique UUID generated for the simulated advancement. This field is only returned if it is a simulation

advancement_request_idinteger

This field is returned only if it's an actual advancement request (EFFECTIVE)

typestring

Operation type, returns either SIMULATION or EFFECTIVE

currency_codestring

ISO-4217 alphabetic (3 characters) currency code.

begin_datestring date

Used for searching merchant transactions. This is the start date of your search range

end_datestring date

Used for searching merchant transactions. This is the end date of your search range

request_datestring date

Advancement request date

Example response

{
  "currency_code": "BRL"
}

Changes

No recorded changes to this operation across all 1 revision of this API.