# Payment runs

A Payment run contains a list of supplier payments. A Payment run can be 
- created by a user with a `CREATOR` role 
- confirmed by a user with a `CONTROLLER` role
- funded by a user with a `CONTROLLER` role

Note that the Controller user must have their mobile device enrolled to SCA. 

Before a payment run can be executed, it must be funded. Users with the `CONTROLLER` role must link their company's bank account(s) that are represented as Linked Accounts, which than can be used as the funding source for a payment run.

Depending on the bank's constraints it may not be possible to deposit the total amount of funds required for a payment run, in which case the payment run will be automatically split into funding groups. All funding groups must be funded and executed for the payment run to be marked as completed. 

Note that even if the payment is created successfully, you still need to check its status in order to determine if it is `completed` or`failed`.


## Create a payment run

 - [POST /v1/payment_runs](https://api.weavr.io/products/payment-run/openapi/payment-runs/postpaymentrun.md): Create a new payment run containing a list of outstanding supplier payments.

Note that all the supplier payments in a payment run is limited to one currency. The currency of the payment run are enabled upon the Buyer’s registration.


Required user role: CREATOR

## Get payment runs

 - [GET /v1/payment_runs](https://api.weavr.io/products/payment-run/openapi/payment-runs/getpaymentruns.md): Retrieve the list of payment runs belonging to the buyer that the logged-in user belongs to.

Required user roles: CONTROLLER OR CREATOR

## Get a payment run

 - [GET /v1/payment_runs/{payment_run_id}](https://api.weavr.io/products/payment-run/openapi/payment-runs/getpaymentrunsid.md): Retrieve a payment run belonging to the buyer that the logged-in user belongs to.


Required user roles: CONTROLLER OR CREATOR

## Update a payment

 - [PUT /v1/payment_runs/{payment_run_id}](https://api.weavr.io/products/payment-run/openapi/payment-runs/putpaymentrunsid.md): Update the details of a payment identified by the paymentId that is in the PENDING_CONFIRMATION state.


Required user role: CREATOR

## Confirm a payment run

 - [POST /v1/payment_runs/{payment_run_id}/confirm](https://api.weavr.io/products/payment-run/openapi/payment-runs/postpaymentrunsidconfirm.md): Confirm that a payment run can be executed.


Required user role: CONTROLLER

## Get a payment run funding instructions

 - [GET /v1/payment_runs/{payment_run_id}/fund](https://api.weavr.io/products/payment-run/openapi/payment-runs/getpaymentrunsidfund.md): Start the the funding process of a payment run.

Specify the funding source of the payment run by providing an id to an already linked account.

Depending on the maximum payment amount constraints imposed by the bank that is providing the account, the payment run may be split in 2 or more groups. Note that you'll need to complete a funding process for each instruction returned.


Required user role: CONTROLLER

## Cancel a payment run

 - [POST /v1/payment_runs/{payment_run_id}/cancel](https://api.weavr.io/products/payment-run/openapi/payment-runs/postpaymentrunsidcancel.md): Cancel a payment run. 

Note that a payment run can be cancelled when it is in the states QUEUED, PENDING_CONFIRMATION, PENDING_CHALLENGE, OR PENDING_FUNDING


Required user roles: CONTROLLER OR CREATOR

## Cancel a payment

 - [PUT /v1/payment_runs/{payment_run_id}/cancel/payments](https://api.weavr.io/products/payment-run/openapi/payment-runs/putcancelpaymentrunpayment.md): Cancel a payment within a payment run. 

Note that a payment can be cancelled when it is in the state PENDING_CONFIRMATION.


Required user roles: CONTROLLER OR CREATOR

## Restart a payment run

 - [POST /v1/payment_runs/{payment_run_id}/restart](https://api.weavr.io/products/payment-run/openapi/payment-runs/postrestartpaymentrun.md): Restart a payment run after it has entered status SCA_FAILED.


Required user role: CONTROLLER

## Cancel a payment run group

 - [POST /v1/payment_runs/{payment_run_id}/group/{group_reference}/cancel](https://api.weavr.io/products/payment-run/openapi/payment-runs/postcancelpaymentrungroup.md): Cancel a payment run group
Note that a payment run group can only be cancelled when it is in the state AWAITING_FUNDS.


Required user role: CONTROLLER