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