Understand common payment fields

Several operations reuse the same small JSON shapes. This page explains every parent object and leaf field once. An operation page tells you whether that shape is required, optional, or conditional for that operation.

How to read a property rule

For every property, answer these five questions before writing code:

1. Who sends it? Blinc sends every request property. The institution sends every response property.
2. Must it exist? Required means present and non-null. Optional means it may be omitted or null as the operation states. Conditional means the stated condition decides.
3. What exact value is normal? Use the operation example and code-values page. A standard example value is not permission to invent a missing value.
4. What does it control? The explanation states whether the field is for routing, identity, money movement, reconciliation, display, or security.
5. What happens when it is wrong? Validate before changing account or financial state. Return the documented transport or protected business rejection.

No required property has an automatic default. If Blinc omits a required request property, reject the
request. If the institution must return a required response property, it must calculate or copy that
property as described; it must not leave it blank.

Amount

{ "Amt": 2500.00, "Ccy": "NGN" }

Code wrapper

{ "Cd": "OTHR" }

Generic identifier

{
  "Othr": {
    "Id": "0123456789",
    "SchmeNm": { "Cd": "NUBAN" }
  }
}

When a field explicitly permits an International Bank Account Number, Id.IBAN is the complete IBAN text and Id.Othr is omitted. Do not send both forms unless a separate rule explicitly allows it.

Party

{
  "Nm": "Ada Okafor",
  "Id": { "Othr": { "Id": "12345678901", "SchmeNm": { "Cd": "BVN" } } }
}

Account

{
  "Id": { "Othr": { "Id": "0123456789", "SchmeNm": { "Cd": "NUBAN" } } }
}

Financial institution

{
  "FinInstnId": {
    "BICFI": "EXAMPLEBIC",
    "Name": "Example Issuer",
    "ClrSysMmbId": { "MmbId": "000001" }
  }
}

Payment identifiers

Payment classification

Remittance and invoice information

Charges

Debit Authorization, Credit Transfer, and Credit Notification each carry the fee that Blinc's
FeeBreakdown computes for that operation, but the total fee is charged once; never added or
subtracted a second time by summing role shares on top of it.

• Debit Authorization charges the full FeeBreakdown.TotalFee once. Chrgs shows that
  amount as FEE and also shows the issuer's share as COMMISSION. The commission is part of
  the fee breakdown, not an extra charge. TtlChrgs equals the FEE amount, and
  NetSttlmAmt equals InstdAmt minus that one fee. See its own operation guide.
• Credit Transfer uses the same Chrgs/TtlChrgs/NetSttlmAmt shape, but every item's Tp
  must equal ACQUIRER; it carries FeeBreakdown.AcquirerShare only. See its own
  operation guide.
• All three adjustment-bearing messages carry TttlCharges inside
  RmtInf.Strd.RfrdDocAmt.AdjstmntAmtAndRsn; it reports the complete transaction fee while
  Amt continues to identify the adjustment's specific share.
• Credit Notification carries FeeBreakdown.PaymentFacilitatorShare in that adjustment,
  with Rsn fixed to PAYMENT_FACILITATOR. See
  Remittance adjustment reasons and its own
  operation guide.

Across all three operations: amounts are in major currency units (not minor/cents), a zero share
must be sent explicitly rather than omitted or null-dropped, and every charge/adjustment currency
must match InstdAmt.Ccy (or the entry amount currency for Credit Notification).

Merchant and terminal

Payment result

Next

Read Understand code values before building an operation.