A campaign is the first logical object that has to be created, once a company has been registered in the system.

Creating a campaign

You can create a campaign by calling POST Create Campaign and providing the following data:

{
  "companyId": "USR03VRXZ1726000668",
  "name": "Name of the new campaign",
  "description": "Description of the new campaign",
  "targetAmountMin": "100000.00",
  "targetAmountMax": "120000.00",
  "currency": "EUR",
  "closeDate": "30/12/2017"
}

Every campaign is related to a company, and has a specific name and description.
The targetAmountMin is the minumum amount of funds that need to be collected from investors to state that the campaign is successful. Please note that this limit may be modified, and that it constrains the possibility of closing the campaign once the campaign reaches its end.
The targetAmountMax is the maximum amount of funds that may be collected; this limit does not imply any operational limitation on the subsequent operations on the campaign.
The closeDate is the date after which the campaign will be considered closed; on that date, the Equity Crowdfunding Portal should invoke PUT Campaign Closed and avoid the creation of new order subscriptions.

Updating a campaign

Once a campaign has been created, it may be updated by invoking PUT Update Campaign. Please note that only name, description, targetAmountMin and targetAmountMax fields may be updated.

Opening a campaign

Once a campaign has been created, it should be opened by invoking PUT Campaign Open in order to allow the creation of new order subscriptions.

Managing an open campaign

While a campaign is open, you can create order subscriptions from your investors. There are a few functions that help you managing an open campaign.
You can retrieve the amount of funds collected on a specific campaign by calling GET Campaign Amount.
You can retrieve the full list of orders of a specific campaign by calling GET Campaign Orders.
You can retrieve the full list of investors that have places an order on a specific campaign by calling GET Campaign Investors.

Closing a campaign

At the end of its duration, a campaign should be closed by invoking PUT Campaign Closed and avoid the creation of new order subscriptions.

Finalizing a successful campaign

Once a campaign has been closed, it must be finalized. The finalization of a campaign is the last action that has to be performed, and depends on the result of the campaign itself.

If the campaign was successful (i.e., at least the targetAmountMin amount of funds has been collected), the campaign should be put in FINALIZED_SUCCESS status by invoking PUT Campaign Success and providing the following data:

{
  "ordersToExecute": [
    "ORD4387623841827947",
    "ORD4387623841827124",
    "ORD4387623841809974"
  ],
  "ordersToUndo": [
    "ORD2309823841827364"
  ],
  "orderToSplit": {
    "orderId": "ORD2309823842182736",
    "companyAmountToExecute": "600.00",
    "companyAmountToUndo": "400.00",
    "feeAmountToExecute": "60.00",
    "feeAmountToUndo": "40.00"
  }
}

The ordersToExecute array contains the full list of IDs of all the order objects that must be aggregated to cashout the collected funds. This array must contain at least one order ID. The cashout operation is performed by bulking all the collected funds and executing a unique money transfer directed to the company bank account.
The ordersToUndo array contains the full list of IDs of all the order objects that must be refunded to the respective investor. This array may be empty. The refund operation is perfomed by refunding each investorby providing a money back of the originally submitted funds on the original submission channel (i.e., if the order was payed through a credit card, a money back on the same credit card will be executed).
The orderToSplit object contains the information of the unique order that may be splitted across the targetAmountMax amount, if required.

Once the campaign has been finalized, a campaignCashout is created to provide details about the actual execution of the money transfer to the company. You can retrieve such details by calling GET Campaign Cashoutusing the cashoutId returned by the PUT Campaign Success call.

Finalizing an unsuccessful campaign

If the campaign was unsuccessful (i.e., the amount of funds collected was not at least equal to targetAmountMin), the campaign should be put in FINALIZED_FAIL status by invoking PUT Campaign Failure. Please note that this endpoint does not require any additional parameted other than the ID of the campaign; the effect of finalizing a campaign with unsuccess is that the entire amount of collected funds is refunded to the investorsthat have subscribed an order for that campaign. The refund operation is performed as described above.

Cancelling a campaign

If you have created a campaign but you need to discard it, you can cancel a campaign by invoking PUT Campaign Cancelled. Please note that the campaign must be either in CREATED, OPEN or CLOSED status. If the campaign is in OPEN or CLOSED status, there must be no orders created for the campaign itself.

A moneyout is the internal financial flow associated with an order. The creation of moneyouts happens automatically when the system receives a moneyin matching with a waiting order and performs the routing instructions provided by the order creation instruction.
Once a moneyout has been created, it means that:

• The related orderAmount has been transferred to the company account dedicated to the campaign
• The related feeAmount has been transferred to your fee collection account (this cash component is optional)

You can retrieve the full list of moneyouts by calling GET Order Payment Moneyouts. For each element of the list, you have access to some basic descriptive properties as shown in the example below.

"moneyout" : {
    "moneyoutId": "MO171743030374714XDN8M544",
    "orderId": "TRX201703141743034503BTAO",
    "companyId": "USR03OGDXBF1709000024",
    "requestedDate": "14/03/2017 17:43:03",
    "status": "REQUESTED",
    "totalAmount": "105.00",
    "feeAmount ": "5.00",
    "companyAmount": "100.00",
    "cashoutAvailableAmount": "100.00",
    "currency": "EUR"
}

A refund is automatically created whenever an order is returned to its investor. You cannot explicitly create a refund since the system automatically manages a refund creation in the following cases:

• When you require the cancellation of an already accounted order;
• When you finalize an unsuccessful campaign, a new refund will be created for each one of its orders.

Each refund is executed accordingly to the channel of the related moneyin; i.e., if the moneyin happened through a credit card transaction, then the refund is performed by requiring a write off of the corresponding transactions; if the moneyin happened through a money transfer, then the refund is performed by a money transfer as well.

You can retrieve a refund by calling GET Order Payment Refund; the call will return some basic descriptive properties as shown in the example below.

"refund" : {
    "refundId": "MB0536717121200E7YV8K13121",
    "orderId": "TRX20170308174401625CTVMSP",
    "companyId": "USR036K3SKK1708000013",
    "description": "Refunding payment TRX20170308174401625CTVMSP",
    "requestedDate": "13/03/2017 05:12:01",
    "executedDate": "13/03/2017 07:11:38",
    "status": "EXECUTED",
    "failDescription": "",
    "companyAmount": "100.00",
    "currency": "EUR"
}

A dispute happens whenever an investor requires a refund of a specific credit card transaction directly to his/her bank, without contacting the equity crowdfunding portal.
The typical process that leads to the creation of a dispute is as follows:

1. An investor may ask to be refunded for the total (or partial) amount of a transaction that has been processed on his/her credit card. This process may be initiated directly by the issuer bank of the investorcredit card, with no interaction with the equity crowdfunding portal that handled the transaction. The reason that motivate such request may be related to fraud suspects (e.g., the credit card has been stolen) or because of commercial reasons (e.g., the payer has not received the items - this case should not happen in equity crowdfunding).
2. As a consequence, the issuer bank requires the cerdit card circuits to open a dispute, in order to get a refund for the investor.
3. Whenever such event happens, then a dispute is created and the equity crowdfunding portal is notified via email.
4. In order to properly handle each dispute, you will be requested to provide all the documentation that may help to contest the dispute and submit evidence to try to reverse the payer repudiation and reclaim the funds.

As a consequence of this process, a dispute may be closed as either:

• WON In this case, the dispute will not result in any effect;
• LOST In this case, the equity crowdfunding portal is asked to provide the funds to fully refund the investor. These funds are automatically debited to the equity crowdfunding portal cash account.

If a dispute is created, you may have evidence of such event by requesting the list of disputes with GET Disputes. For each element of the list, you have access to some basic descriptive properties as shown in the example below.

"dispute" : {
    "disputeId": "DSP170309HS5D6V101",
    "orderId": "TRX20170308155833621AYEY2A",
    "orderAmount": "30.0",
    "status": "OPEN",
    "openDate": "25/02/2017",
    "closeDate": ""
}

An exception is an unattended event that prevents the system from its expected behavior. Usually, an exception is a signal of something that went wrong while performing some action.
Three levels of severity of exceptions may be expected:

• WARNING: typically, is raised whenever the system required your attention on some specific event that requires your intervention to be addressed, but that is not blocking the correct execution of the expected workflow.
• ERROR: is raised whenever something wrong happened in the internal subsystem. Your intervention is not explicitly required, but be prepared to be contacted by our service assistance in order to help solve the problem.
• CRITICAL: is raised whenever something wrong happened while moving funds in the internal subsystem. Your intervention is not explicitly required, but be prepared to be contacted by our service assistance in order to help solve the problem.

If an exception is raised, you may have evidence of such event by requesting the list of exceptions with GET Exceptions. For each element of the list, you have access to some basic descriptive properties as shown in the example below.

"exception": {
    "exceptionId": "EXSPLT1222917030219IVZYRX14241",
    "description": "Cash out error",
    "objectId": "COU17131212834031008VHWWDI",
    "objectType": "CASH_OUT",
    "priority": "CRITICAL",
    "status": "OPEN"
}

A unidentified transfer is a money flow that is received by the equity crowdfunding portal that cannot be matched with any order in created or waiting status.
More specifically, a unidentified transfer can be originated in these occasions:

1. A money transfer without a orderId. If no orderId is provided in the description of an incoming money transfer, then it cannot be recognized as a potential moneyin for any order. As a consequence, the incoming transfer is marked as unidentified transfer.
2. A money transfer with an invalid orderId. If an orderId is provided in the description of an incoming money transfer, but it cannot be matched with the orderId of any order in created/waiting status, then the incoming transfer is marked as unidentified transfer.
3. A money transfer with a valid orderId, but with an incorrect totalAmount. A money transfer with an incorrect totalAmount is marked as unidentified transfer since it cannot be correctly matched with any orderin created/waiting status. Please note that the investor should be notified to repeat the money transfer with the correct orderId and totalAmount, since it is not allowed to aggregate moneyins (i.e., for each order one and only one moneyin is expected).

Whenever an unidentified transfer is detected, the system automatically reacts by rejecting the money transfer and sending back to the investor exactly the same amount of money received. You cannot interact, configure or modify this mechanism, since it is put in place in order to preserve the correct alignment of the money flows of the system itself.
If an unidentified transfer is detected, you may have evidence of such event by requesting the list of unidentified transfers with GET Unidentified Transfers. For each element of the list, you have access to some basic descriptive properties as shown in the example below.

{
    "unidentifiedtransferId" : "UTR170309AHMC07172815000001",
    "type" : "UNIDENTIFIED",
    "status" : "SENT_BACK",
    "amount" : "120.00",
    "currency" : "EUR",
    "description" : "An unexpected money transfer",
    "payerName" : "John Doe"
}