API development and system integrations

Banking and payment APIs are precision work, not decoration. Gateways, core banking, IBAN inquiry, or batch settlement each have a contract, cutoff hours, and sample documents. KGSM asks for a real sample before estimating or the date will float.

Audience, risk, and how KGSM works

A technical or finance lead who must connect a gateway, core bank, or settlement service to an internal system

An integration without unique ids and daily matching means orphan deposits, double vouchers, and hours of mismatch on busy days.

KGSM puts transaction status on the same finance document and ships webhooks plus a matching job in version one.

One id, one status

Every payment attempt has an internal id mapped to the gateway id. Gateway success with panel failure gives support two stories. User return, webhook, and delayed inquiry must converge. We keep logs without raw card data and set explicit payment-link timeouts.

Give every payment a unique internal id. No webhook, only browser return; a dropped user left an orphan order.

Core banking in the real world

Not every bank offers clean REST. Discovery includes the bank test environment, caps, and a named counterpart. No SLA on their side means a conditional date on ours. Installment tables must match core postings. The treasurer role is not the developer with the API key on a laptop.

The production key sat on a developer laptop and rotating it after they left took a day. Webhooks and user return must share one status.

Match, fees, audit

A daily matching job surfaces gaps the same day. Gateway fees sit on the receipt. Audit reports show who retried an inquiry. Backups run before batch settlement files. Shop, CRM, and finance share the payment id.

Automate daily matching. Bank cutoff hours were missing from the estimate and afternoon branch settlement failed.

Connection security

Gateway keys live in server env, not git. We test IP allowlists and webhook signatures. Test and production stay apart. Viewing a transaction is not executing settlement. The contract states what happens to orders when the bank is down.

Fees were ignored in profit and margin was wrong for three months. Keep gateway keys out of git.

See the bank test environment before you estimate. A double inquiry posted two vouchers for one deposit.

Raw card numbers in logs made an incident unmanageable. Store fees on the receipt.

Split treasurer from developer access. No webhook, only browser return; a dropped user left an orphan order.

The production key sat on a developer laptop and rotating it after they left took a day. Back up before batch settlement files.

Implementation checklist

• Give every payment a unique internal id.
• Webhooks and user return must share one status.
• Automate daily matching.
• Keep gateway keys out of git.
• See the bank test environment before you estimate.
• Store fees on the receipt.
• Split treasurer from developer access.
• Back up before batch settlement files.

Field scenario 1

No webhook, only browser return; a dropped user left an orphan order.

Give every payment a unique internal id.

Field scenario 2

The production key sat on a developer laptop and rotating it after they left took a day.

Webhooks and user return must share one status.

Field scenario 3

Bank cutoff hours were missing from the estimate and afternoon branch settlement failed.

Automate daily matching.

Field scenario 4

Fees were ignored in profit and margin was wrong for three months.

Keep gateway keys out of git.

Field scenario 5

A double inquiry posted two vouchers for one deposit.

See the bank test environment before you estimate.

Field scenario 6

Raw card numbers in logs made an incident unmanageable.

Store fees on the receipt.

Approximate investment

A single documented gateway usually costs less than a full system; core banking and batch settlement are estimated separately. If counterpart test access slips, so does our date.

FAQ

Do you only integrate Zarinpal?

Common Iranian gateways and any API that provides documents and a test environment. Each core bank is its own discovery.

How long does it take?

A well-documented gateway is often two to six weeks after test access. Core banking depends on their SLA.

What about PCI and card data?

We do not store raw cards; gateway tokens are enough. Scope is in the security contract.

Will it hit accounting?

Payment status sits on the same finance document or exports to your accounting package.

Related KGSM pages

• برنامه‌نویسی وب KGSM
• تماس و برآورد

When you apply this on a live team, write it as an operating rule, not a slide: Give every payment a unique internal id. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Webhooks and user return must share one status. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Automate daily matching. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Keep gateway keys out of git. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: See the bank test environment before you estimate. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Store fees on the receipt. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Split treasurer from developer access. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Back up before batch settlement files. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: No webhook, only browser return; a dropped user left an orphan order. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: The production key sat on a developer laptop and rotating it after they left took a day. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Bank cutoff hours were missing from the estimate and afternoon branch settlement failed. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Fees were ignored in profit and margin was wrong for three months. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: A double inquiry posted two vouchers for one deposit. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Raw card numbers in logs made an incident unmanageable. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: An integration without unique ids and daily matching means orphan deposits, double vouchers, and hours of mismatch on busy days. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: KGSM puts transaction status on the same finance document and ships webhooks plus a matching job in version one. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: A technical or finance lead who must connect a gateway, core bank, or settlement service to an internal system Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: A single documented gateway usually costs less than a full system; core banking and batch settlement are estimated separately. If counterpart test access slips, so does our date. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Give every payment a unique internal id. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Webhooks and user return must share one status. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Automate daily matching. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Keep gateway keys out of git. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: See the bank test environment before you estimate. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Store fees on the receipt. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Split treasurer from developer access. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Back up before batch settlement files. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: No webhook, only browser return; a dropped user left an orphan order. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: The production key sat on a developer laptop and rotating it after they left took a day. Then assign an owner and a review date so the rule survives the first busy week.

When you apply this on a live team, write it as an operating rule, not a slide: Bank cutoff hours were missing from the estimate and afternoon branch settlement failed. Then assign an owner and a review date so the rule survives the first busy week.