Follow the integration journey

This guide explains the order of events. You do not need to understand ISO message names before reading it.

What you will build

Create the HTTPS endpoints required for the operations the institution supports:

Endpoint purpose	When Blinc calls it	What the endpoint returns
Account Linking	A customer asks to connect a bank account to a creditor	A new account-linking ID, or a reason the link was rejected
Account Unlinking	A customer or authorised process cancels a link	Confirmation that the account link is cancelled, or a rejection
Debit Authorization	A customer approves a payment from a linked account	Accepted or rejected debit status
Reversal	Blinc needs to return a completed debit	Accepted or rejected reversal status
Credit Notification	Blinc reports that a credit event occurred	Confirmation that the notification was recorded
Credit Transfer	Blinc instructs the acquiring institution to credit a beneficiary	Accepted or rejected credit status

You choose the URLs. For example, a Debit Authorization endpoint might be:

https://sandbox.examplebank.com/blinc/debit-authorizations

Send the complete URL to Blinc during onboarding. Do not copy an example URL; it does not point to your system.

Step 1: exchange public information

Blinc and the institution exchange public keys, endpoint URLs, test data, and network requirements. Blinc also issues the institution's six-digit member code. Configure that exact code in message IDs and routing fields.

Private keys stay with their owners:

Blinc's private key never leaves Blinc.
The institution private key never leaves the institution's controlled environment.

Step 2: connect the customer's account

Blinc sends Account Linking for Ada Okafor and account 0123456789.

For each Account Linking request:

Decrypt the request with the institution private key.
Does x-signature verify with the Blinc public key?
Is x-timestamp current, and has this request already been used?
Confirm that the request names the receiving institution with the correct member code.
Authenticate the customer using the institution's chosen process.
Confirm the account belongs to that authenticated customer and can be linked.
Confirm the customer approved the link to the named creditor using the institution's chosen consent process. Blinc does not prescribe that process or send a required consent token.
Is the requested account-linking ID new?

If every check passes, create an active account link and return its ID, such as BLINC-EXAMPLE-MANDATE-0001.

Blinc uses that ID on later debit requests. It is not a password; it identifies the institution's stored consent record.

Step 3: authorise one debit

Ada approves NGN 2,500.00 on her registered phone. Blinc sends Debit Authorization.

The request contains three different kinds of evidence:

Evidence	Simple meaning	What you do with it
Institutional signature in `x-signature`	"Blinc sent this exact plaintext message."	Verify it with the Blinc public key after decryption.
Customer-device signature in the payment message	"Ada's registered device approved these customer-visible transaction details."	Verify it with the device public key stored during linking.
Authentication context	"This is how Ada authenticated and which registered authenticator was used."	Validate the context, type, hardware, numeric key ID, and actor as one consistent set.

Also check the account link, customer, creditor, amount, currency, identifiers, dates, and replay state.

Return:

ACSC when the debit was accepted and recorded; or
RJCT when it was rejected, together with a reason code and a sentence explaining what must be corrected.

An HTTP 200 response can contain either business result. Blinc reads the decrypted status.

Step 4: handle an uncertain network result

What Blinc does after a timeout depends on the operation:

Operation that timed out	What Blinc does next
Debit Authorization	Blinc does not resend the debit request. Blinc sends Reverse using the original debit references.
Account Linking	Blinc does not resend the link request. The customer starts Account Linking again, using new identifiers.
Account Unlinking	Blinc does not resend the unlink request. The customer starts Account Unlinking again, using new identifiers.
Credit Notification	Blinc may resend the same notification with the same business identifiers and plaintext.
Credit Transfer	Blinc may resend the same transfer with the same business identifiers and plaintext.
Reverse	Blinc may resend the same Reverse request with the same business identifiers and plaintext.

When Debit Authorization times out, the debit might have completed even though Blinc did not receive the response. The institution must use the original references in the later Reverse request to find the debit. If the debit was accepted, return the funds once. If no accepted debit exists, reject Reverse with NOOR. Never create a second debit while resolving the timeout.

For the three operations that Blinc may resend, return the stored result for an identical request and never apply the business action twice.

Step 5: reverse the debit when required

Blinc sends Reversal with the original debit's identifiers, amount, and currency.

Before accepting a Reversal, confirm that:

the original debit exists and was accepted;
the requested amount and currency match the original debit;
the debit has not already been reversed; and
the reversal identifiers have not been used for a different request.

After returning the funds, respond with ACSC. Otherwise respond with RJCT and an actionable reason.

Step 6: disconnect the account

Blinc sends Account Unlinking with the account-linking ID and a cancellation reason. Mark the account link cancelled and return confirmation.

After cancellation, any new debit using that account link must be rejected.

Step 7: support incoming credits when applicable

If the institution receives beneficiary credits, implement Credit Transfer and Credit Notification. The security sequence is unchanged: decrypt, verify, validate, process once, sign the result, and encrypt it for Blinc.

Read Set up security and keys, then implement Account Linking.