Bulk credits sweep account

[remear]

Missing scenarios

#707 (comment)

• credit several orders into a settlement (credit settlement)
• credit several orders and reverse a previous credit into a settlement (nett settlement)
• reverse a previous credit into a settlement (debit settlement)
• attempt to settle an account with no unsettled transfers
• settle account with negative balance from a bank account
• settle account with negative balance from an order with available funds in escrow_amount

Missing features

• credit.json needs to accept a funding instrument with prefix AT
• marketplaces.json should return links for settlements and accounts

[mjallday]

did you mean to keep transfers in the spec?

[remear]

No. Copied from the original PR.

[mahmoudimus]

Does every bank account get a sweep_account associated with it?

[mahmoudimus]

How do debits work from a bank account that has a sweep_account associated with it?

[mjallday]

i think the reason we went with transfers as opposed to credit/debits for these transactions is this:

you created a credit to the sweep account from order /orders/123123.
now when you look at /orders/123123/credits it would not exist because it was not a credit to the order. when i look at /orders/123123/debits would i see a debit? that doesn't make sense if so, we just created a credit.

with a transfer all you see is a transfer, it's omnidirectional it had a source of the order balance and a destination of the sweep account.

[mjallday]

currently this is a 400

curl https://api.balancedpayments.com/debits      -H "Accept: application/vnd.api+json;revision=1.1"      -u ak-test-D4i8c5COSld5I3XkSkXIUBLtGhpN6X67:      -d "appears_on_statement_as=Statement text"      -d "amount=5000"      -d "description=Some descriptive text for the debit in the dashboard"

{
  "errors": [
    {
      "status": "Bad Request",
      "category_code": "request",
      "additional": null,
      "status_code": 400,
      "category_type": "request",
      "extras": {
        "source": "Missing required field [source]"
      },
      "request_id": "OHM61d85cea597611e4bc0006429171ffad",
      "description": "Missing required field [source] Your request id is OHM61d85cea597611e4bc0006429171ffad."
    }
  ]
}

[mjallday]

looking 👍 @remear.

[mjallday]

@remear is customer_deposit_account the correct terminology for this? we've informally called it a sweep account internally which i'm not too tied to but from reading the official definition

A deposit account is a savings account, current account, or other type of bank account, at a banking institution that allows money to be deposited and withdrawn by the account holder.

it sounds very generic and the same term could apply to several of the funding instruments within the Balanced API.

[remear]

Let's refer to it as sweep_account.

[mjallday]

I had a bit of a deeper think about this spec, here's what I think we need to flesh out:

• reversals

  A settlement can have a combination of credits and reversals of previously succeeded credits. This allows customers to cover the refunding of a debit associated with an order with the funds about to be paid out from another order.

  For example, if I credit out to Order1 and then settle it (everything succeeds eventually in this scenario) and then want to refund the debits that made up the balance for Order1 then I need to credit my own funds (as the marketplace) into Order1 or I can use funds from Order2 (to the same merchant) to cover the amount. In this scenario I would then credit the funds from Order2 and reverse the credit from Order1. After the settlement succeeds I should see funds from Order2 move into Order1.

  Users are asking for this because it's much faster than waiting on funds to come back from the merchant and they perceive it as being much simpler since they only have to show a single net settlement of funds to their customers.

• debit settlements

  If in the above scenario I want to refund a previously paid out order but I do not have funds from another order within the Balanced system, I will need to debit the merchant.

  In this case I would create a reversal of the credit associated to a previously succeeded settlement and then create a new settlement. This settlement would have a negative balance which would result in a debit against the merchant's bank account

• failed settlements

  If a settlement fails due to either an invalid funding instrument or lack of funds then I need to be able to re-initiate the settlement.

  I'm not sure of the best way to achieve this just yet, the two options we have are:

  1. say that the settlements FAILED state is terminal and ask the user to create a new settlement - this is the correct behavior if a settlement is a transaction/transfer of funds.
  2. say that the settlement is an accounting construct and it has a transaction/transfer of funds. if this is the case then we can ask the user to update the funding instrument on the settlement and this will then reset the state and attempt to settle the funds a second time.

  @balanced/spec-ialz i'd like feedback as to which method of retrying is preferred. I would like to use the same method of retry for invoices when they are exposed. for invoices currently we update the funding instrument which creates a new fee settlement transfer under the covers. you do not create a new invoice. we could change this behavior but imo both a settlement and an invoice is an accounting construct similar to an order, not an actual movement of funds. please give us feedback ASAP as this will block completion of this feature.

@remear can you please implement the reversal and debit settlement scenarios in this pull-request? thanks! :)

[matin]

In this case I would create a reversal of the credit associated to a previously succeeded settlement and then create a new settlement. This settlement would have a negative balance which would result in a debit against the merchant's bank account

@mjallday We may be using different words to describe the same thing ... I suggest reversal should still happen against the account even if it means that the balance of the account becomes negative. That allows the marketplace to net the reversal against future credits or perform a settlement of a negative amount.

on retrying ... keep it explicit—no automatic retry. Why does a settlement have to be treated like a transaction to work?

[matin]

Why is this here/necessary?

[mjallday]

needs the following on the marketplaces.

diff --git a/fixtures/marketplaces.json b/fixtures/marketplaces.json
index 79cc9cf..8ced423 100644
--- a/fixtures/marketplaces.json
+++ b/fixtures/marketplaces.json
@@ -70,6 +70,16 @@
                     "type": "string",
                     "format": "uri",
                     "pattern": "/disputes"
+                },
+                "marketplaces.settlements": {
+                    "type": "string",
+                    "format": "uri",
+                    "pattern": "/settlements"
+                },
+                "marketplaces.accounts": {
+                    "type": "string",
+                    "format": "uri",
+                    "pattern": "/accounts"
                 }
             },
             "required": [
@@ -84,6 +94,8 @@
                 "marketplaces.callbacks",
                 "marketplaces.card_holds",
                 "marketplaces.orders",
+                "marketplaces.settlements",
+                "marketplaces.accounts",
                 "marketplaces.disputes"
             ]
         },