Check status on payment
After successfully initiating a payment, you will receive a response with the ID of the payment and the status of the payment. The status returned will always be PendingProcessing, unless the payment information provided is invalid, in which case the status returned will be Rejected. The PendingProcessing response is a validation that Banking Circle has received the payment and that it has been sent to processing in our systems. To check the status of a payment, you can either call our payments status endpoints or sign up for our notifications subscription service
Payment status
How to look up the status of a payment will depend on whether the initial payment submitted via the Single Payment API or the Bulk Payment API. Payments initiated via the Bulk Payments API can also be looked up via the Single Payments API, but require some more steps as explained below.
For Single Payments
To get the status of a single payment, use the endpoint api/v1/payments/singles/{payment-id}/status with the ID of the payment received as response to the payment initiation.
Example of the request URL for Single Payment Status Retrieval:
https://sandbox.bankingcircleconnect.com/api/v1/payments/singles/9ffa7024-5536-4b0f-9578-d03171f75182/status
The response contains the status of the payment and no other parameters:
{
"status": "Processed"
}
For Bulk Payments
To get the overall status of a bulk payment, use the endpoint api/v1/payments/bulks/{payment-bulk-id}/status with the ID of the payment received as response to the payment initiation.
Example of the request URL for Payment Bulk Status Retrieval:
https://sandbox.bankingcircleconnect.com/api/v1/payments/bulks/be0c7c7d-8dba-471c-822a-8e5ba340e97e/status
The response contains the status of the payment bulk and no other parameters:
{
"status": "Processed"
}
The status returned is the aggregated status of all payments in the bulk. This means that in case 51% of payments has been processed, the returned status will be processed.
To read a more detailed overview of the bulk status, use the api/v1/payments/bulks/{payment-bulk-id} endpoint. Using this endpoint will return general information about the bulk and an overview of the statuses for the payments within the bulk:
{
"paymentBulkId": "f3822099-8316-4487-bceb-32c5e89352de",
"concurrencyToken": "1638789624",
"status": "Approved",
"instructedDate": "2021-12-06T00:00:00+00:00",
"paymentStatistics": {
"processed": 232,
"pendingProcessing": 0,
"rejected": 0,
"missingFunding": 0,
"cancelled": 0,
"pendingApproval": 0,
"pendingSca": 0,
"scaDeclined": 0,
"scaExpired": 0,
"declinedByApprover": 0,
"total": 232,
"aggregatedAmount": 274933
}
}
Individual payments submitted via a Bulk Payments API can also be found via the Single Payment API. You can use the api/v1/payments/singles endpoint to search for payments based on status or another parameter.
Payment statuses
Payment Status | Description |
---|---|
Processed | Payment has been successfully processed. This is a final state for the payment and means that the payment has passed all validation checks and has been sent to the receiver. |
PendingProcessing | Payment is waiting to be processed. |
MissingFunding | Payment has not been processed due to insufficient funding on debtor account. Payment will stay in MissingFunding and automatically be processed when the account is funded. If the account is not funded in 10 days, the payment will be Rejected. |
Rejected | Payment has been rejected. See below for possible rejection reasons. |
Cancelled | Payment has been cancelled by your company. |
Reversed | Payment has been rejected by the payment scheme. |
Returned | Payment has been returned by the receiver’s financial institution. Read about returned payment reasons here. Returned is not an actual state, as the payment will be processed, but will be returned as an incoming payment. |
Reasons for rejection
A payment is either rejected because it has been in MissingFunding for 10 days, or because one or more of the fields has been populated with an invalid value. A payment can be rejected up front or after it has hit our core system. You can look up the rejection reason by using the GET /api/v1/payments/singles or GET /api/v1/payments/singles/{payment-id} endpoint to look up the payment and read the rejection reason.
Below is an example of the returned data for the two endpoints. The rejection reason can be found in the “errors” field.
{
"paymentId": "690a72db-aa73-4d48-974b-7b26abdcd164",
"transactionReference": "TRANS221122323",
"concurrencyToken": "1638789624",
"classification": "Outgoing",
"status": "Rejected",
"errors": "InvalidAccountFormat",
"lastChangedTimestamp": "2021-12-04T11:20:24.4550414+00:00",
"debtorInformation": {
"paymentBulkId": null,
"accountId": "2b5e1669-57b6-48ac-9506-e61a58f19e72",
"account": {
"account": "EUR33226473",
"financialInstitution": "INST88339944",
"country": "ES"
},
"vibanId": null,
"viban": {
"account": "DKK77338844",
"financialInstitution": "INST88339944",
"country": "ES"
},
"instructedDate": null,
"debitAmount": {
"currency": "EUR",
"amount": 266
},
"debitValueDate": "2021-12-06T00:00:00+00:00",
"fxRate": null,
"instruction": null
},
"transfer": {
"debtorAccount": null,
"debtorName": null,
"debtorAddress": null,
"amount": {
"currency": "USD",
"amount": 244
},
"valueDate": null,
"chargeBearer": null,
"remittanceInformation": null,
"creditorAccount": null,
"creditorName": null,
"creditorAddress": null
},
"creditorInformation": {
"accountId": "afd128ed-be84-4c7c-abe3-a08531bbf9cf",
"account": {
"account": "EUR33226473",
"financialInstitution": "INST88339944",
"country": "ES"
},
"vibanId": null,
"viban": {
"account": "DKK77338844",
"financialInstitution": "INST88339944",
"country": "ES"
},
"creditAmount": {
"currency": "EUR",
"amount": 266
},
"creditValueDate": "2021-12-06T00:00:00+00:00",
"fxRate": null
}
}
To see the status of a rejected payment from a bulk, use the GET /api/v1/payments/singles endpoint and filter on PaymentBulkId and Status.
Below is a list of the possible rejection reasons, and an explanation for each. The list contains both upfront validation errors and processing errors.
Error code | Error description |
---|---|
InvalidDebtorAccount | You do not have permission to access selected debtor account or debtor account does not exist |
CreatePaymentWithAdhocCreditorPermissionViolation | You do not have permission to instruct payment with ad hoc creditor from selected debtor account |
BulkPaymentCreatePermissionViolation | You do not have permission to instruct payment from selected debtor account |
CreateOwnPaymentPermissionViolation | You do not have permission to instruct own payment from selected debtor account |
CreateOutgoingPaymentPermissionViolation | You do not have permission to instruct outgoing payment from selected debtor account |
MandatoryMissing | Mandatory field cannot be empty |
InvalidAmountLength | Number of characters exceeds maximum allowed length |
InvalidAmountFormat | Amount not formatted correctly |
InvalidAmountPrecisionForCurrency | Number of amount decimals not supported by amount currency |
MaxEurThresholdViolation | Amount exceeds maximum allowed value |
MinEurThresholdViolation | Amount below minimum allowed value |
InvalidAmountZero | Amount cannot be zero |
UserAmountLimitViolation | Outgoing transfer amount exceeds threshold limit |
InvalidCurrency | Unsupported or invalid currency |
InvalidDateFormat | Date format not supported |
RequestedExecutionDateDaysInPastThresholdViolation | Requested Execution Date exceeds allowed number of days in the past |
RequestedExecutionDateDaysInFutureThresholdViolation | Requested Execution Date exceeds allowed number of days in the future |
InvalidIbanChecksum | IBAN checksum is invalid |
InvalidAccountFormat | Unsupported account format |
InvalidDebtorVibanRelation | VIBAN cannot be found |
InvalidBankingCircleAccount | Not an account with Banking Circle |
InvalidExternalAccount | Invalid creditor account format, only IBAN allowed |
InvalidTransferDebitAndCreditToSameAccount | Debit and credit account cannot be the same |
InvalidFinancialInstitution | Invalid BIC/clearing code format |
ForbiddenTransferToCountry | Creditor financial institution reside in country where Banking Circle cannot transfer funds |
InvalidAccountAndFinancialInstitutionCombination | Combination of IBAN and financial institution is invalid |
InvalidLength | Number of characters exceeds maximum allowed length |
InvalidChargeBearer | Unsupported charge bearer |
InvalidDebtorViban | VIBAN cannot be found |
InvalidCharacters | CPF field validation failed |
ProcessingError | Error processing the payment |
DuplicateFileUpload | Identical file already uploaded once for this user. Change the content of the file and try again |
InvalidDebtorAccountCurrencyAmountCurrencyAndTransferCurrencyCombination | Amount currency must match either debtor account currency or transfer currency |
ConflictingConfiguration | Targeted debtor accounts have conflicting configuration |
ForbiddenCurrencyToCountry | The chosen currency is forbidden to send to the country of the receiver. |
InvalidCreditorIdentifierAndAdHocCreditorExclusivityCombination | Creditor ID field contains an invalid value. Error in creditor information |
InvalidCreditorIdentifier | Creditor ID field contains an invalid value. Creditor ID is the identifier for a stored beneficiary |
NoApprovers | Approval required but no approvers exist |
InvalidCsvMaximumNumberOfLines | Number of lines (payments) above maximum allowed |
InvalidCsvMinimumNumberOfLines | Number of lines (payments) below minimum allowed |
InvalidCsvFileSize | File size exceeds allowed maximum |
InvalidCsvFileExtension | Unsupported file extension |
InvalidCsvPaymentLineLength | Content of single line (payment) exceeds maximum allowed length |
InvalidCsvPaymentLineNumberOfFields | Number of fields (comma separated) does not match requirement |
InvalidContentType | Content Type is not supported |