Approve a debit

Approve a customer's debit after confirming the customer, device provisioning, payment, and account details. The issuing institution must verify that the customer approved the payment on a registered device and that the device credential, payment details, and account checks all pass before moving any money.

Before you begin

• Provision the customer's device credential and store the deviceCredentialProvisionId plus the customer device public key.
• Implement Secure every request and response.
• Follow How to Encrypt and Decrypt Data for the request envelope and message-opening sequence.
• Follow Format identifiers and date-times.
• Read Understand common payment fields.
• Read Understand code values.
• Support idempotent lookup by message, instruction, end-to-end, transaction, and client references.
• Store enough data to validate a later Reversal request.
• Configure the institution member code issued by Blinc and the permitted creditor schemes.

Endpoint

Create an HTTPS POST endpoint and give its complete URL to Blinc.

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

Every request must contain Content-Type: application/json, Accept: application/json, x-timestamp, and x-signature. Every response, including a business rejection, must contain Content-Type: application/json, x-timestamp, and x-signature. See Secure every request and response for what each header protects and how to validate it.

Request business message

After the request has been opened and its institutional signature verified as described in How to Encrypt and Decrypt Data, the business message looks like this:

{
  "GrpHdr": {
    "MsgId": "00000120260817101530123000000000001",
    "CreDtTm": "2026-08-17T10:15:30.123Z",
    "NbOfTxs": 1,
    "SttlmInf": {
      "SttlmMtd": "CLRG",
      "ClrSys": {
        "Prtry": "BLINC"
      },
      "ClrChanl": "RTNS"
    }
  },
  "DbtAuthInf": {
    "PmtId": {
      "InstrId": "DD-INSTR-0001",
      "EndToEndId": "DD-E2E-0001",
      "TxId": "DD-TX-0001",
      "ClrSysRef": "DD-CLR-0001"
    },
    "deviceCredentialProvisionId": "7f2c1a9e-3b44-4d21-9c66-0a1b2c3d4e5f",
    "PmtTpInf": {
      "SvcLvl": {
        "Cd": "SLEV"
      },
      "CtgyPurp": {
        "Cd": "GDAS"
      },
      "LclInstrm": {
        "Cd": "BLINC"
      },
      "SeqTp": "OOFF"
    },
    "InstdAmt": {
      "Amt": 1500.0,
      "Ccy": "NGN"
    },
    "IntrBkSttlmAmt": {
      "Amt": 1500.0,
      "Ccy": "NGN"
    },
    "IntrBkSttlmDt": "2026-08-17T00:00:00.000Z",
    "ChrgBr": "SLEV",
    "Dbtr": {
      "Nm": "Ada Okafor",
      "Id": {
        "Othr": {
          "Id": "12345678901",
          "SchmeNm": {
            "Cd": "BVN"
          }
        }
      }
    },
    "DbtrAcct": {
      "Id": {
        "Othr": {
          "Id": "0123456789",
          "SchmeNm": {
            "Cd": "NUBAN"
          }
        }
      }
    },
    "DbtrAgt": {
      "FinInstnId": {
        "BICFI": "EXAMPLEBIC",
        "Name": "Example Bank",
        "ClrSysMmbId": {
          "MmbId": "000001"
        }
      }
    },
    "CdtrAgt": {
      "FinInstnId": {
        "BICFI": "CREDITORBIC",
        "Name": "Creditor Bank",
        "ClrSysMmbId": {
          "MmbId": "000002"
        }
      }
    },
    "Cdtr": {
      "Nm": "Example Store",
      "Id": {
        "Othr": {
          "Id": "CREDITOR-001",
          "SchmeNm": {
            "Cd": "BLINC"
          }
        }
      }
    },
    "CdtrAcct": {
      "Id": {
        "Othr": {
          "Id": "0987654321",
          "SchmeNm": {
            "Cd": "NUBAN"
          }
        }
      }
    },
    "RmtInf": {
      "Ustrd": "Debit authorization for online purchase",
      "Strd": null
    },
    "Chrgs": [
      {
        "Tp": "FEE",
        "Cd": "FEE001",
        "Amt": {
          "Amt": 50.0,
          "Ccy": "NGN"
        },
        "Rcpt": {
          "BICFI": "FEEBICX",
          "Name": "Fee Recipient",
          "ClrSysMmbId": {
            "MmbId": "000001"
          }
        }
      },
      {
        "Tp": "COMMISSION",
        "Cd": "COM001",
        "Amt": {
          "Amt": 20.0,
          "Ccy": "NGN"
        },
        "Rcpt": {
          "BICFI": "COMBICX",
          "Name": "Commission Recipient",
          "ClrSysMmbId": {
            "MmbId": "000001"
          }
        }
      }
    ],
    "TtlChrgs": {
      "Amt": 50.0,
      "Ccy": "NGN"
    },
    "NetSttlmAmt": {
      "Amt": 1450.0,
      "Ccy": "NGN"
    },
    "DbtAuth": {
      "AuthntcnCntxt": {
        "AuthntcnTmstmp": "2026-08-17T10:14:30.000Z",
        "ElctrncSgntr": "<BASE64_CUSTOMER_DEVICE_SIGNATURE>",
        "auth_context": "DEVICE_LOCAL_AUTH",
        "auth_type": "DEVICE_BIOMETRIC_STRONG",
        "auth_binding": {
          "hardware": "SECURE_ENCLAVE",
          "key_id": 42
        },
        "auth_actor": "CUSTOMER"
      },
      "CdtrSchmeId": {
        "Id": {
          "PrvtId": {
            "Othr": {
              "Id": "CREDITOR-001",
              "SchmeNm": {
                "Cd": "BLINC"
              }
            }
          }
        }
      }
    }
  },
  "SplmtryData": {
    "PlcAndNm": "AdditionalDetails",
    "Envlp": {
      "Message": {
        "Amount": 1500.0,
        "ClientReference": "CLIENT-REF-0001"
      },
      "CustomerDeviceLocation": "{\"latitude\":6.5244,\"longitude\":3.3792}",
      "TerminalId": null,
      "TerminalTimestamp": null,
      "TerminalLocation": null,
      "TerminalReference": null,
      "DeviceId": "DEVICE-0001",
      "DeviceName": "Ada's registered phone",
      "TransactionHash": "HASH-0001",
      "ClientReference": "CLIENT-REF-0001",
      "PaymentMethod": "P2P"
    }
  }
}

What this request contains

The request identifies the customer account, the merchant payment, the amount, the customer's approval, and the device credential provisioning record that authorizes the debit. The customer's approval is signed inside the protected message. The institution must verify that approval before debiting the account or crediting the payment beneficiary.

Verify the customer-device signature

ElctrncSgntr is not the same as the institutional x-signature header.

1. Take the exact SplmtryData.Envlp.Message object shown to the customer for approval.
2. Serialize it as compact JSON with null properties omitted.
3. Join the request's x-timestamp value and that JSON with no separator.
4. Convert the joined string to uppercase.
5. Verify ElctrncSgntr using the device public key stored with deviceCredentialProvisionId during device credential provisioning.

Reject the debit when the signed customer-visible amount/reference differs from the debit fields.

Decide whether to approve the debit

1. Decrypt and verify the institutional signature headers.
2. Validate timestamp, replay state, message ID, and transaction identifiers.
3. Confirm the debtor institution member ID identifies the receiving institution.
4. Load the device credential provisioning record by deviceCredentialProvisionId and require active status.
5. Match the customer and debtor account to the stored device credential provisioning record.
6. Validate the authentication fields as one combination.
7. Verify the customer-device signature.
8. Confirm the instructed amount, currency, settlement date, charges, and net settlement arithmetic agree: net settlement amount = instructed amount - TotalFee (the FEE amount).
9. Perform the institution's balance, risk, limit, sanctions, and account-status checks.
10. Record one business outcome and preserve every original reference so a later Reversal can identify this debit.
11. Sign and encrypt the response, then return the required response headers.

If no response reaches Blinc

Blinc does not retry Debit Authorization. If the connection fails after the institution may have completed the debit, Blinc sends a Reversal request using the original debit references.

When the Reversal arrives, find the original debit by those references. If the debit was accepted, return the full amount once. If no accepted debit exists, return RJCT with NOOR. Do not create a new debit while handling a Reversal, and do not wait for Blinc to resend Debit Authorization.

Request field reference

Header and settlement

Identifiers, device credential, and payment classification

Amount, parties, and accounts

Narration, charges, and net settlement

Additional transaction details

Successful response

Return a signed and encrypted payment response. The readable response is:

{
  "GrpHdr": {
    "MsgId": "00000120260816102501000000000000102",
    "CreDtTm": "2026-08-16T10:25:01.000Z",
    "OrgnlMsgId": "12345620260816102500000000000000003",
    "OrgnlMsgNmId": "pacs.003.001.11"
  },
  "TxInfAndSts": {
    "OrgnlInstrId": "DD-INSTR-0001",
    "OrgnlEndToEndId": "DD-E2E-0001",
    "OrgnlTxId": "DD-TX-0001",
    "TxSts": "ACSC",
    "StsRsnInf": null,
    "SplmtryData": {
      "PlcAndNm": "AdditionalDetails",
      "Envlp": { "CustomParam": { "PostingReference": "INST-POST-0001" } }
    }
  }
}

Rejection response

Use TxSts: "RJCT" and populate:

Test before certification

• A valid customer request with an active device credential returns ACSC once.
• Fee-only, full-issuer-share, and partial-issuer-share requests all reconcile as net settlement amount = instructed amount - TotalFee (the FEE amount), with COMMISSION as the contained IssuerShare and not an additional deduction.
• After a simulated timeout, Blinc does not resend Debit Authorization; it sends a Reversal with the original debit references.
• Reversal returns the accepted debit once, or returns RJCT with NOOR when no accepted debit exists.
• Missing, inactive, unknown, or mismatched deviceCredentialProvisionId returns RJCT.
• Institutional signature or customer signature failure rejects before posting.
• Changed Message.Amount or client reference fails the customer signature or consistency check.
• Missing, zero, string-valued, or wrong key_id rejects.
• Unsupported or contradictory authentication context/type/hardware/actor rejects.
• HTTP 200 containing RJCT is handled as a business rejection.

Next

Learn how to return clear errors and handle repeated deliveries.