Attach an unattached credit to an invoice

curl --request POST \
  --url https://api.panoflow.io/v1/inbound-credits/{inbound_credit_id}/match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "invoice_id": "ivc_01JM9S346Q3D25VT4F5V37E3S3"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({invoice_id: 'ivc_01JM9S346Q3D25VT4F5V37E3S3'})
};

fetch('https://api.panoflow.io/v1/inbound-credits/{inbound_credit_id}/match', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.panoflow.io/v1/inbound-credits/{inbound_credit_id}/match"

payload = { "invoice_id": "ivc_01JM9S346Q3D25VT4F5V37E3S3" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "response_code": "00",
  "response_message": "Approved or completed successfully",
  "id": "<string>",
  "object": "inbound_credit",
  "created_at": "2026-10-27T08:41:00Z",
  "amount": {
    "amount": 45000000,
    "currency": "NGN"
  },
  "status": "matched",
  "received_at": "2026-10-27T08:41:00Z",
  "received_into": {
    "type": "invoice_virtual_account",
    "account_number": "8012457739"
  },
  "updated_at": "2026-10-27T08:41:00Z",
  "fee": {
    "amount": 45000000,
    "currency": "NGN"
  },
  "payer": {
    "account_number": "8012457739",
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_name": "<string>"
  },
  "payer_contact": {
    "name": "<string>",
    "phone": "+2348031234567",
    "email": "jsmith@example.com"
  },
  "narration": "<string>",
  "session_id": "<string>",
  "matched_to": {
    "type": "invoice",
    "id": "<string>",
    "label": "<string>",
    "reference": "<string>",
    "matched_by": "account_number"
  },
  "credited_account": {
    "id": "<string>",
    "name": "<string>",
    "account_number": "8012457739"
  },
  "transaction_id": "<string>",
  "checkout_id": "<string>",
  "matched_at": "2026-10-27T08:41:00Z"
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Inbound credits

Attach an unattached credit to an invoice

For a transfer that landed in one of your accounts without an invoice number in the narration. The money is already in your account, so no money moves and your balances don’t change; this only records the credit against the invoice (unattached → matched), updating the invoice’s amount_paid and status and firing invoice.paid when it is now paid in full. Allowed only for unattached credits and invoices in sent, partially_paid or overdue. The credit can be attached to one invoice, once.

Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, scope_missing, csrf_token_invalid, idempotency_key_reused, currency_mismatch, rate_limited.

POST

inbound-credits

{inbound_credit_id}

match

Attach an unattached credit to an invoice

curl --request POST \
  --url https://api.panoflow.io/v1/inbound-credits/{inbound_credit_id}/match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "invoice_id": "ivc_01JM9S346Q3D25VT4F5V37E3S3"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({invoice_id: 'ivc_01JM9S346Q3D25VT4F5V37E3S3'})
};

fetch('https://api.panoflow.io/v1/inbound-credits/{inbound_credit_id}/match', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.panoflow.io/v1/inbound-credits/{inbound_credit_id}/match"

payload = { "invoice_id": "ivc_01JM9S346Q3D25VT4F5V37E3S3" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "response_code": "00",
  "response_message": "Approved or completed successfully",
  "id": "<string>",
  "object": "inbound_credit",
  "created_at": "2026-10-27T08:41:00Z",
  "amount": {
    "amount": 45000000,
    "currency": "NGN"
  },
  "status": "matched",
  "received_at": "2026-10-27T08:41:00Z",
  "received_into": {
    "type": "invoice_virtual_account",
    "account_number": "8012457739"
  },
  "updated_at": "2026-10-27T08:41:00Z",
  "fee": {
    "amount": 45000000,
    "currency": "NGN"
  },
  "payer": {
    "account_number": "8012457739",
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_name": "<string>"
  },
  "payer_contact": {
    "name": "<string>",
    "phone": "+2348031234567",
    "email": "jsmith@example.com"
  },
  "narration": "<string>",
  "session_id": "<string>",
  "matched_to": {
    "type": "invoice",
    "id": "<string>",
    "label": "<string>",
    "reference": "<string>",
    "matched_by": "account_number"
  },
  "credited_account": {
    "id": "<string>",
    "name": "<string>",
    "account_number": "8012457739"
  },
  "transaction_id": "<string>",
  "checkout_id": "<string>",
  "matched_at": "2026-10-27T08:41:00Z"
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Server API key, scoped. pk_test_ keys hit the sandbox tenant.

Headers

Idempotency-Key

string

Optional on non-money POSTs; honoured when sent.

Required string length: 1 - 255

X-Request-Id

string

Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always our own req_… id. We log your value with the request as client_request_id, so support can find a request by either id. A longer value is refused with 400 parameter_invalid.

Maximum string length: 128

Path Parameters

inbound_credit_id

string

required

Inbound credit id (icr_…).

Pattern: ^icr_[0-9A-HJKMNP-TV-Z]{26}$

Body

application/json

invoice_id

string

required

Invoice to record the credit against (ivc_…).

Response

The credit, now matched.

Money received (icr_…), recorded once it has been credited to your account. A money-movement object, so it carries ResponseOutcome (CONVENTIONS §7a), which is always 00: matched and unattached are both credited to your account (unattached only lacks an invoice, link or virtual account).

response_code

enum<string>

required

Two-character ISO 8583 response code, using the NIBSS NIP meanings (CONVENTIONS §7a). 00 is success. Carried on every error (mapped from error.code, see errors.yaml x-codes) and on every money-movement object (the bank's final code, or our own while it is in flight). Clients must tolerate codes added later.

Available options:

00,

01,

03,

05,

06,

07,

08,

09,

12,

13,

14,

15,

16,

17,

21,

25,

26,

30,

34,

35,

51,

57,

58,

61,

63,

65,

68,

91,

92,

94,

96,

97

Pattern: ^[0-9A-Z]{2}$

response_message

string

required

Standard meaning of the code (the x-codes text), not customer copy. Customer-safe wording is in status_reason / error.message.

Example:

"Approved or completed successfully"

string

required

icr_…

object

string

required

Always inbound_credit.

Allowed value: "inbound_credit"

created_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

amount

object

required

An amount in minor units (kobo, cents) with its currency. Never a decimal.

Show child attributes

status

enum<string>

required

Every inbound credit a business sees is already credited to one of its accounts.

matched: credited to your account and recorded against an invoice, payment link or static virtual account.
unattached: credited to your account, but not tied to any invoice, link or virtual account (e.g. a transfer to Naira · Main without an invoice number). Attach it with matchInboundCredit.

Available options:

matched,

unattached

received_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

received_into

object

required

The account number the payer sent to.

Show child attributes

updated_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

fee

object

Collection fee charged on this credit, if the business's plan has one. Posted separately.

Show child attributes

payer

object

The sending account, from the bank. account_name is the name the bank reported.

Show child attributes

payer_contact

object

Details the payer typed on a pay page checkout, when there was one.

Show child attributes

narration

string

Narration sent with the transfer.

session_id

string

NIP session id.

Pattern: ^\d{30}$

matched_to

object

What the credit was matched to. For unattached credits type is account.

Show child attributes

credited_account

object

One of the business's own PanoFlow accounts (owned by the Accounts service).

Show child attributes

transaction_id

string

Transaction (txn_…) in the account view, once credited.

checkout_id

string

Pay page checkout (cko_…) this credit paid, when there was one.

matched_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

Accounts & transactions

Payments

Collections

Payroll

Approvals

Webhooks & events

OAuth

Attach an unattached credit to an invoice

Authorizations

Headers

Path Parameters

Body

Response