IDCanopy Developers

Payments

Account-to-account payment initiation, status, and challenge deposit verification

What it returns

A hosted redirect to initiate an A2A bank payment, a status lookup for that transaction, and a challenge-deposit (penny drop) identity check against an IBAN.

Payment sequence

Initiate a payment and check its status
Initiate a payment and check its statusYour backend to Payments API: POST /payments/initiate. Payments API to Your backend: Return requestId and redirectUrl. Your backend to User / browser: Open redirectUrl. User / browser to Payments API: Complete hosted bank authorisation. Payments API to User / browser: Navigate to returnUrl. Your backend to Payments API: POST /payments/status with referenceId. Payments API to Your backend: Return status and statusReasonInformationUser / browserYour backendPayments API1. POST /payments/initiate2. Return requestId and redirectUrl3. Open redirectUrl4. Complete hosted bank authorisation5. Navigate to returnUrl6. POST /payments/status with referenceId7. Return status andstatusReasonInformation

Bank authorisation is represented within the hosted flow. A browser return is not payment confirmation or settlement evidence. Use the server-side status result; the challenge-deposit identity check is a separate operation.

Request

POST /payments/initiate

FieldRequiredDescription
referenceIdyesUnique transaction identifier you generate
transactionDescriptionyes
returnUrlyesRedirect target after payment
IBANyesRecipient's IBAN
currencyyes
amountyesDecimal string
storedBIC / language / countryno

POST /payments/status, note this is POST, not GET. { "referenceId": "..." }.

POST /payments/challenge-deposit

FieldRequiredDescription
amountyesSmall verification amount, e.g. "0.10"
currencyyes3-letter code
descriptionyesAlphanumeric and hyphens only
firstName / lastNameyesFor identity verification
piiToggleyes0 or 1, whether PII is returned
nameMatchLogicyesexact or fuzzy

Response

initiate returns requestId and redirectUrl (the hosted payment page). status returns status (one of PROCESSING, SUCCESS, INITIATED, PENDING, PENDING_EXTERNAL_AUTHORIZATION, FAILURE_*, SETTLEMENT_*, COMPLETED, FAILED) and statusReasonInformation. challenge-deposit returns transactionId, status (OK/FAIL), globalResult.overall (review/pass/fail), globalResult.totalScore, nameMatchScore, and, when piiToggle is 1, iban, returnedFirstName, returnedLastName.

Decision

The caller decides from status for a payment's progress, and from globalResult.overall plus nameMatchScore for a challenge deposit's identity match.

Test cases

Test cases are not available yet. Contact IDCanopy: office@idcanopy.com.

Reference

Third-party sandbox bank credentials for testing are issued with your sandbox access; ask your IDCanopy contact.

The operations of this topic and the token call. The full Umbrella API reference has every topic.

Send request against Production or Sandbox needs a bearer token from POST /auth and a server-side or allowed origin. In the browser, use Mock.

On this page