Online Payments API

The United Clearing Center (UCC) payment gateway. Banks and other agents use it to verify a customer against a service provider, check their debt, execute the payment, reconcile totals at the end of the business day, and register clearing orders — all through UCC's Extended Services System (ESS).

How it works

UCC sits between service consumers (banks) and service providers (SPs) — mobile operators, internet providers, utilities, and so on. For each SP incorporated into UCC, up to four general services are published. Only the payment service is always present; the rest depend on what the SP's own interface supports:

Most SPs provide debt (or verify) plus payment. Which services exist for a given SP — and the NCI codes to call them with — comes from the catalog (see getServiceProviders).

Integration flow

• Sync the catalog. Call getServiceProviders to load every SP's metadata: services, NCI service codes, bank accounts, treasury codes, and commission tables. Cache it and refresh periodically.
• Identify the customer. Call the SP's verify or debt service through NCI with the customer's abonentCode to confirm identity and, for debt, fetch the outstanding balance.
• Take the payment. Call the SP's payment service through NCI with the amount, currency, abonent code, your own unique agentPaymentId, and your businessDayId. UCC returns its paymentId and your commission.
• Correct same-day mistakes. If the SP supports it, cancel a payment via NCI — possible only while the associated business day is still open.
• Close the day. Call reconcile with your business day ID and summary totals. UCC compares them against its own records and closes the day.
• Register clearing. Generate clearing orders on your side and publish them via registerClearingOrder, associating the covered payment IDs — strongly recommended only for reconciled operations.

Authentication & security

Online Payments does not use a separate API key or OAuth token. Instead, every SOAP envelope — NCI and UCC web services alike — must be encrypted and signed per the WS-Security specification, using an X.509 certificate registered with UCC for your agent account.

The envelope may optionally carry a WS-Security <Timestamp> element.

The shape below follows the generic OASIS WS-Security standard (not specific to UCC's spec) — included so the algorithms above make sense in context.

Certificate exchange

Trust between your system and UCC is mutual: each side generates its own X.509 key pair, signs its outgoing messages with its own private key, and gives the other side its public certificate for verification/decryption. Nobody issues a certificate on the other party's behalf — you generate yours, UCC generates theirs, and you exchange the public halves. One certificate pair covers your agent account — the same keys sign both NCI calls and UCC web service calls.

• Generate your key pair. Create an X.509 key pair on your side, using whatever standard tooling your team already uses (OpenSSL, Java keytool, or similar), and store it in a keystore of your choice. The keystore itself — its type, your alias names, its password — is entirely internal to you; none of it is shared with or dictated by UCC.
• Send UCC only your public certificate. Export the public certificate (not the keystore, not the private key) and send it to your UCC integration contact. This is the only artifact that crosses the boundary in this direction.
• Import UCC's public certificate into your own keystore once you receive it from UCC, so your side can verify/decrypt what UCC signs.
• Test. Confirm the exchange worked by having UCC synchronize your agent record on their side — your integration contact will run this check with you. A signed getServiceProviders call (no parameters, read-only) is a convenient first end-to-end smoke test.
• Renewal follows the same flow: generate a new key pair, send the new public certificate to UCC, and import UCC's public certificate again if UCC has also rotated theirs.

SOAP conventions

Two contracts, two conventions. NCI calls (verify / debt / payment / cancel) all go through one generic gateway operation, execute, defined by the NCI WSDL — the concrete action is selected by the serviceId you pass. UCC web services (reconcile, getPayments, registerClearingOrder, getServiceProviders) are ordinary WSDL-defined SOAP operations on a separate contract.

NCI gateway — verified against the WSDL

Target namespace (both variants): http://nci.connector.ess.azry.com/ · document/literal binding. See NCI endpoint variants for the differences between the two endpoints and full wire examples.

UCC web services

NCI endpoint variants

UCC publishes the NCI gateway in two flavors. Both live in the same namespace, expose the same two operations, and take the same logical model — serviceId plus key/value parameters. They differ only at the transport layer, and the one difference that matters is how errors come back. Pick the variant that matches your stack and use it consistently; the examples below switch together.

execute — wire examples

errorKey carries the NCI error code (see Errors & fault codes); invalidParameter, when present, names the offending input parameter.

bulkExecute — batching (both variants)

bulkExecute wraps multiple executeRequest items in one call. Per-item outcomes come back in-band in both variants: each ExecuteResult carries either parameter values or faultEntries — a SOAP Fault is not used here even on the standard endpoint, and results are positional (the n-th result answers the n-th request).

Environments

Errors & fault codes

There are two error families. NCI error codes are returned by the per-provider verify / debt / payment / cancel calls and use the com.azry.ess.error.* namespace; they can vary from SP to SP — the table below lists only the important codes common to all SPs. On the wire the code travels in the errorKey field, delivered as a SOAP Fault (EssFault) on the standard NCI endpoint or as an in-band faultEntry on the WCF endpoint — see NCI endpoint variants. UCC error codes are thrown by the UCC web services as a UCCException carrying an error code and message.

NCI error codes

Full code values carry the com.azry.ess.error. prefix, e.g. com.azry.ess.error.Abonent_not_found.

UCC error codes (UCCException)

Fault structure

The guide defines UCCException as an error code plus a message. Branch on the code, not the human-readable message. The exact XML shape of the fault detail comes from the WSDL — the example below is illustrative:

Validates a customer's abonent code in the service provider's system. Optional — published only if the SP's interface supports it. Invoke via NCI using the service's verifyServiceCode.

Input parameters

Output parameters

Retrieves the customer's outstanding debt in the service provider's system. Optional — published only if the SP's interface supports it. Invoke via NCI using the service's debtServiceCode.

Input parameters

Output parameters

Executes the payment. Always published for every SP. Invoke via NCI using the service's payServiceCode.

Input parameters

Output parameters

Possible NCI errors

Pre_payment_error Non_unique_agent_payment_id Payment_network_failure Validation_failure Abonent_not_found General

On the wire, these parameters travel as key/value pairs inside a single execute call — see NCI endpoint variants for the full envelope.

Cancels an already-performed payment. Optional — published only if the SP's interface supports it. Invoke via NCI using the service's cancelServiceCode.

Input parameters

Possible UCC errors

UNKNOWN_PAYMENT WRONG_CANCEL_AMOUNT WRONG_CANCEL_CURRENCY PAYMENT_ALREADY_CANCELED PAYMENT_BUSINESS_DAY_CLOSED

The guide defines no output parameters for cancel — treat a fault-free response as success and confirm final state via payment status (CANCELLING → CANCELED). To be verified against the WSDL.

Closes a business day by exchanging summary totals with UCC. Send your business day ID plus the count and summary amount of successfully performed payments; UCC responds with its own expected figures and the resulting day status.

Request parameters

Response

Possible faults

UNKNOWN_BUSINESS_DAY SYSTEM_INTERNAL_ERROR

Retrieves all payments associated with a business day — useful for investigating an irregular reconciliation or rebuilding your local ledger.

Request parameters

Response

Publishes a clearing order on the UCC server and associates payments to it. Clearing with SPs is performed by banks themselves — registration on UCC is for informational purposes, giving the SP a clear view of performed or upcoming funds transfers. It is strongly recommended to register clearing only for reconciled operations.

Request parameters

Possible faults

UNKNOWN_SERVICE_PROVIDER UNKNOWN_PAYMENT ILLEGAL_CLEARING_PAYMENT ILLEGAL_CLEARING_CURRENCY ILLEGAL_CLEARING_SP_CODE WRONG_CLEARING_AMOUNT NON_UNIQUE_BANK_ORDER_NUMBER

WRONG_CLEARING_AMOUNT means the clearing order's amount must equal the summary amount of the referenced payments — recalculate before resubmitting.

Returns the full catalog of service providers incorporated into UCC — company details, bank accounts, treasury codes, provided services with their NCI codes, and commission tables. Takes no parameters.

Response

Two further operations are referenced by the Integration Guide but not defined in it:

Payment

The full payment record as stored by UCC — returned by getPayments.

ReconciliationResult

Returned by reconcile. (Spelled ReconcilationResult in the guide's schema diagram — verify against the WSDL.)

ClearingOrder

The clearing order document passed to registerClearingOrder.

ServiceProvider

Top-level catalog record returned by getServiceProviders.

ServiceProviderAccount

TreasuryCode

Service

A single service provided by an SP. The four *ServiceCode fields are the identifiers you pass to NCI to invoke the corresponding call.

ServiceCommission

A single row of a service's commission table — the input to the commission algorithm.

Payment statuses

Lifecycle statuses of a payment within UCC:

Business day statuses

Payment lifecycle & the grey state

• PERFORMING. Your NCI payment call is in flight to the SP. If the call returns normally you receive paymentId and commission and the payment lands in PERFORMED; an SP-side refusal lands it in REJECTED.
• Failure before the SP. Pre_payment_error guarantees the payment message never left for the SP — nothing was performed, so you may safely resubmit (keep the same agentPaymentId only if the original call produced no payment record; on Non_unique_agent_payment_id, check via getPayment first).
• Failure after the SP — FAILED. Payment_network_failure means the connection dropped and UCC cannot tell whether the SP performed the payment. The status is a genuine unknown; the guide prescribes manual investigation (telephone or email between SP and UCC staff) as the only resolution path.
• Cancellation. Where the SP supports it, cancel moves the payment through CANCELLING to CANCELED — but only while the business day is still OPENED.

Business day & clearing

• Open a day. Choose a unique businessDayId and stamp it on every payment you take. The day is OPENED for as long as you keep transacting under it.
• Keep totals as you go. You will need the count and summary amount of successfully performed payments for reconciliation.
• Reconcile at day end. Call reconcile. The day closes no matter what: CLOSED_NORMAL on a match, CLOSED_IRREGULAR on a mismatch. Use getPayments to pull UCC's view of the day when investigating an irregular close.
• Clear reconciled operations. Generate clearing orders in your systems and register them via registerClearingOrder, listing the covered paymentIds. The guide strongly recommends clearing only reconciled operations.

Commission calculation

For each consumed payment, UCC calculates the commission dedicated to the service consumer (i.e. the bank) from the service's commission table (shipped with the catalog — see ServiceCommission).

The record is matched on amount range, currency, payment channel, and consumer code. If no record matches, paymentChannel is excluded from the query first, then serviceConsumerCode — so provider-wide defaults act as fallbacks for channel- or bank-specific rows. If no record can be found at all, getCommission fails with COMMISSION_CALCULATION_ERROR.