Bulk Payment process

Experimental

Bulk payments are an experimental feature: the API and its behaviour may change in future releases.

A bulk payment lets an end user, who already registered the consent for a financial account, send several SEPA payments from one of the connected accounts to different creditors, authorising the whole batch only once with their Financial Institution.

Please note that:

• the Financial Institution holding the account has to support SEPA payments, otherwise the request is rejected with a 422 Unprocessable entity http error;
• the debtor account must have an IBAN, otherwise the request is rejected with a 422 Unprocessable entity http error;
• the batch is validated as a whole: if a single payment is invalid (for example a wrong IBAN), the request is rejected and none of the payments is created;
• in the sandbox environment the sum of every payment of the batch must be less than 10 EUR, otherwise the request is rejected with a 402 Payment required http error.

Steps

1. The Registered End User asks to start the bulk payment process.
2. The Software Integrator sends a POST to Start a bulk payment, with the accountUuid of the debtor account and the list of payments.
3. A-Cube API responds with the uuid of the bulk payment and a connectUrl.
4. The software integrator sends this URL to the Registered End user.
5. The Registered End user clicking on the URL will be redirected to the Financial Institution holding the account.
6. The process will continue on the website of the Financial Institution, where the Registered End user authorises all the payments at once.
7. If process is successful, the Registered End user will be redirected to the optional returnUrl, when it has been specified in the request; otherwise a page summarizing the batch (number of payments and total amount) will be displayed. In case of error the Registered End user will be redirected to the optional errorUrl, or to an error page.
8. At this point A-Cube will call the payment Webhook once for every payment of the batch.

Request

{
  "accountUuid": "c83ea9a5-78aa-4bd8-9e9a-fe46827603f9",
  "returnUrl": "https://example.com/done",
  "errorUrl": "https://example.com/error",
  "payments": [
    {
      "amount": "120.00",
      "currencyCode": "EUR",
      "description": "Invoice 001",
      "creditorIban": "IT85C0300203280285976469459",
      "creditorName": "Giuseppe Verdi"
    },
    {
      "amount": "80.50",
      "currencyCode": "EUR",
      "description": "Invoice 002",
      "creditorIban": "IT60X0542811101000000123456",
      "creditorName": "Anna Rossi"
    }
  ]
}

Response:

{
  "uuid": "aaaaaaaa-0000-4000-8000-000000000001",
  "connectUrl": "https://ob.api.acubeapi.com/pay/bulk/aaaaaaaa-0000-4000-8000-000000000001/start"
}

Tracking the batch

Every payment of the batch is a regular payment: it has its own uuid, status and endToEndId, and it carries the bulkUuid field with the identifier of the batch it belongs to. Single payments do not have the bulkUuid field.

You can follow the batch in three ways:

• the payment webhook is sent for each payment of the batch, with the same payload as for single payments plus the bulkUuid field;
• Retrieve a bulk payment returns the batch together with all its payments;
• the payments list can be filtered by batch with the bulk.uuid query parameter.

The status of the batch is derived from the status of its payments:

Status	Meaning
in_progress	the batch has not reached a final state yet
waiting	at least one payment is waiting for the bank to confirm its outcome
partially_failed	some payments failed, the others did not
failed	all the payments failed
confirmed	all the payments were confirmed

As for single SEPA transfers, a successful authorisation does not guarantee that the money has been moved: a payment is confirmed only once it is found among the transactions of the debtor account.