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 orfailed.

Create a payment run

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

SecurityapiKey and authToken

Request

header Parameters

idempotency-ref

string

A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

Request Body schema: application/json

paymentRunRef	string A unique identifier by which you identify the payment run with on your system.
tag	string <= 50 characters ^[a-zA-Z0-9_-]+$ The tag field is a custom field that can be used to search and filter.
description	string The long form description of the payment run
required	Array of objects (Payment) [ 1 .. 1000 ] items The list of payments associated with the payment run

Responses

200

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

409

Conflict

413

Content Too Large

422

Unprocessable Entity

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs

Request samples

Payload

application/json

{"paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
"tag": "string",
"description": "September payment run 01",
"payments": [{"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
}
}
]
}

Response samples

200
400
403
409
default

application/json

{"id": "string",
"paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
"tag": "string",
"description": "September payment run 01",
"createdBy": "110747174434373672",
"status": "PENDING_CONFIRMATION",
"statusReason": "string",
"payments": [{"id": "string",
"status": "QUEUED",
"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
},
"validationOutcomes": [{"category": "UK_CONFIRMATION_OF_PAYEE",
"categoryResult": {"match": "EXACT_MATCH",
"reasonCode": "ANNM",
"accountName": "string"
}
}
]
}
],
"createdAt": "2019-08-24T14:15:22Z"
}

Get payment runs

Retrieve the list of payment runs belonging to the buyer that the logged-in user belongs to.

Required user roles: CONTROLLER OR CREATOR

SecurityapiKey and authToken

Request

query Parameters

limit	integer <int32> [ 1 .. 100 ] Default: 100 The limit of the results for paging, starting at the offset. Limit is always capped at 100.
offset	integer <int32> >= 0 Default: 0 The offset value for paging, indicating the initial item number to be returned from the data set satisfying the given criteria. Leave out to fetch the first page of results.
tag	Array of strings unique Filter by tag. The exact tag must be provided, as wildcards are not supported. Leave out to fetch all entries.
status	string The status of the payment run. Enum: "QUEUED" "CANCELLED" "COMPLETED" "COMPLETED_WITH_ERRORS" "EXECUTING" "INVALID" "PENDING_CHALLENGE" "PENDING_CONFIRMATION" "PENDING_FUNDING" "SCA_FAILED" Example: status=PENDING_CONFIRMATION
reference	string The unique paymentRunRef of the payment run.
min_amount	integer <int64> >= 0 The minimum total amount of the payment run.
max_amount	integer <int64> >= 0 The maximum total amount of the payment run.

Responses

200

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/payment_runs

Response samples

200
400
403
default

application/json

{"count": 10,
"responseCount": 100,
"paymentRuns": [{"id": "string",
"paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
"tag": "string",
"description": "September payment run 01",
"createdBy": "110747174434373672",
"status": "PENDING_CONFIRMATION",
"statusReason": "string",
"payments": [{"id": "string",
"status": "QUEUED",
"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
},
"validationOutcomes": [{"category": "UK_CONFIRMATION_OF_PAYEE",
"categoryResult": {"match": null,
"reasonCode": null,
"accountName": null
}
}
]
}
],
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

Get a payment run

Retrieve a payment run belonging to the buyer that the logged-in user belongs to.

Required user roles: CONTROLLER OR CREATOR

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

Responses

200

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/payment_runs/{payment_run_id}

Response samples

200
400
403
404
default

application/json

{"id": "string",
"paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
"tag": "string",
"description": "September payment run 01",
"createdBy": "110747174434373672",
"status": "PENDING_CONFIRMATION",
"statusReason": "string",
"payments": [{"id": "string",
"status": "QUEUED",
"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
},
"validationOutcomes": [{"category": "UK_CONFIRMATION_OF_PAYEE",
"categoryResult": {"match": "EXACT_MATCH",
"reasonCode": "ANNM",
"accountName": "string"
}
}
]
}
],
"createdAt": "2019-08-24T14:15:22Z"
}

Update a payment

Update the details of a payment identified by the paymentId that is in the PENDING_CONFIRMATION state.

Required user role: CREATOR

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

Request Body schema: application/json
required

required

Array of objects non-empty

Responses

204

No Content

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

put/v1/payment_runs/{payment_run_id}

Request samples

Payload

application/json

{"payments": [{"paymentId": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
}
}
]
}

Response samples

400
403
404
409
default

application/json

{"message": "string",
"syntaxErrors": {"invalidFields": [{"params": ["string"
],
"fieldName": "string",
"error": "REQUIRED"
}
]
}
}

Confirm a payment run

Confirm that a payment run can be executed.

Required user role: CONTROLLER

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

header Parameters

idempotency-ref

string

Responses

200

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

413

Content Too Large

422

Unprocessable Entity

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs/{payment_run_id}/confirm

Response samples

application/json

{"id": "string",
"paymentRunRef": "94fddfb2-297d-423d-9157-4200b7beb834",
"tag": "string",
"description": "September payment run 01",
"createdBy": "110747174434373672",
"status": "PENDING_CONFIRMATION",
"statusReason": "string",
"payments": [{"id": "string",
"status": "QUEUED",
"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
},
"validationOutcomes": [{"category": "UK_CONFIRMATION_OF_PAYEE",
"categoryResult": {"match": "EXACT_MATCH",
"reasonCode": "ANNM",
"accountName": "string"
}
}
]
}
],
"createdAt": "2019-08-24T14:15:22Z"
}

Get a payment run funding instructions

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

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

query Parameters

linkedAccountIds

required

Array of strings unique

The unique identifier of the linked account, that is to be used as the funding source for the payment run.

Note that only one linked account per currency is supported.

Example: linkedAccountIds=652d25b73541d8084a88a38d

Responses

200

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

get/v1/payment_runs/{payment_run_id}/fund

Response samples

application/json

{"count": 10,
"responseCount": 100,
"fundingInstructions": [{"reference": "string",
"totalAmount": {"currency": "GBP",
"amount": 454321
},
"status": "PENDING_FUNDING",
"fundingDate": "2019-08-24T14:15:22Z",
"payments": [{"id": "string",
"status": "QUEUED",
"externalRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentRef": "c99cd66c-82fc-4a01-977b-61a2f5a247a1",
"paymentAmount": {"currency": "GBP",
"amount": 1
},
"reference": "string",
"supplier": {"name": "string",
"address": "string",
"bankName": "string",
"bankAddress": "string",
"bankCountry": "st",
"type": "PERSONAL",
"bankAccountDetails": {"accountNumber": "stringst",
"sortCode": "string",
"secondaryReference": "string"
}
},
"validationOutcomes": [{"category": "UK_CONFIRMATION_OF_PAYEE",
"categoryResult": {"match": null,
"reasonCode": null,
"accountName": null
}
}
]
}
]
}
]
}

Cancel a payment run

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

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

header Parameters

idempotency-ref

string

Responses

204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

413

Content Too Large

422

Unprocessable Entity

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs/{payment_run_id}/cancel

Response samples

400
403
404
409
default

application/json

{"message": "string",
"syntaxErrors": {"invalidFields": [{"params": ["string"
],
"fieldName": "string",
"error": "REQUIRED"
}
]
}
}

Cancel a payment

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

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

header Parameters

idempotency-ref

string

Request Body schema: application/json
required

paymentIds

required

Array of strings non-empty unique

Responses

204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

413

Content Too Large

422

Unprocessable Entity

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

put/v1/payment_runs/{payment_run_id}/cancel/payments

Request samples

Payload

application/json

{"paymentIds": ["string"
]
}

Response samples

400
403
404
409
default

application/json

{"message": "string",
"syntaxErrors": {"invalidFields": [{"params": ["string"
],
"fieldName": "string",
"error": "REQUIRED"
}
]
}
}

Restart a payment run

Restart a payment run after it has entered status SCA_FAILED.

Required user role: CONTROLLER

SecurityapiKey and authToken

Request

path Parameters

payment_run_id

required

string^[0-9a-fA-F]{24}$

The unique identifier of the payment run.

header Parameters

idempotency-ref

string

Responses

204

Success - No Content.

400

Bad Request Error - Your request is invalid.

401

Unauthorized - Your credentials or access token are invalid.

403

Forbidden - Access to the requested resource or action is forbidden.

404

Not found - The requested resource couldn't be found.

409

Conflict

413

Content Too Large

422

Unprocessable Entity

429

Too many requests.

500

Internal Server Error - There is a problem with the server. Please try again later.

503

Service Unavailable - We're temporarily offline for maintenance. Please try again later.

default

Error

post/v1/payment_runs/{payment_run_id}/restart

Response samples

400
403
404
409
default

application/json

{"message": "string",
"syntaxErrors": {"invalidFields": [{"params": ["string"
],
"fieldName": "string",
"error": "REQUIRED"
}
]
}
}

➔ Next to Linked Accounts

Payment runs

Create a payment run

header Parameters

Request Body schema: application/json

Get payment runs

query Parameters

Get a payment run

path Parameters

Update a payment

path Parameters

Request Body schema: application/jsonrequired

Confirm a payment run

path Parameters

header Parameters

Get a payment run funding instructions

path Parameters

query Parameters

Cancel a payment run

path Parameters

header Parameters

Cancel a payment

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Restart a payment run

path Parameters

header Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required