Verify Blockpay ( External )

Verifies the status of a BlockPay payment using the payment reference returned when the payment link was created.

This endpoint can be used by the merchant to retrieve the current status of a BlockPay collection and confirm whether the payment is still pending or has reached a final state.

Endpoint

GET /api/v1/collection/blockpay-verify

Authorization

Bearer Token

A valid Bearer Token is required to authenticate the request.

Headers

Header	Description	Required
`Authorization`	Bearer token used to authenticate the request	Yes
`x-merchant-ref`	Unique reference identifying the merchant	Yes

Query Parameters

Parameter	Description	Required
`payment_ref`	Unique payment reference generated when the BlockPay payment link was created	Yes

Request

curl --location -g '{{base_url}}/api/v1/collection/blockpay-verify?payment_ref=BPAY-TEST-VERIFY-001' \
--header 'Authorization: Bearer <token>' \
--header 'x-merchant-ref: {{vault:x-merchant-ref}}'

Response

{
  "message": "Retrieved Successfully",
  "data": {
    "user_ref": "USR_TEST_004",
    "txn_merchant_ref": "TXN_TEST_VERIFY_001",
    "status": "PENDING",
    "collection": {
      "amount": "350",
      "available_balance_after": "0",
      "available_balance_before": "0",
      "created_at": "2026-09-03T12:00:00.000000Z",
      "currency": "NGN",
      "description": "DYNAMIC_COLLECTION",
      "ledger_balance_after": "0",
      "ledger_balance_before": "0",
      "payment_reference": "BPAY-TEST-VERIFY-001"
    }
  }
}

Response Fields

Field	Description
`message`	Indicates the result of the verification request.
`data.user_ref`	Reference of the user associated with the payment.
`data.txn_merchant_ref`	Merchant's transaction reference associated with the collection.
`data.status`	Current status of the BlockPay payment.
`data.collection`	Contains details of the collection transaction.
`data.collection.amount`	Amount associated with the collection.
`data.collection.available_balance_after`	Available wallet balance after the collection.
`data.collection.available_balance_before`	Available wallet balance before the collection.
`data.collection.created_at`	Date and time the collection was created.
`data.collection.currency`	Currency of the collection.
`data.collection.description`	Description or type of the collection.
`data.collection.ledger_balance_after`	Ledger balance after the collection.
`data.collection.ledger_balance_before`	Ledger balance before the collection.
`data.collection.payment_reference`	Payment reference used to identify the BlockPay payment.

Payment Status

The status field indicates the current state of the payment.

For example:

PENDING

A PENDING status means the payment has not yet reached a final state. The merchant can verify the payment again later to retrieve its updated status.

How It Works

The merchant creates a BlockPay payment link.
LedgerBlock returns a unique payment_ref.
The customer proceeds with the payment through the BlockPay checkout.
The merchant can call the verification endpoint using the payment_ref.
LedgerBlock returns the current payment status and collection details.
The merchant can use the returned status to determine the current state of the payment.

Use Cases

The Verify BlockPay endpoint can be used to:

Check the current status of a BlockPay payment.
Verify a payment using its payment reference.
Retrieve collection details associated with a payment.
Confirm whether a payment is still pending or has reached a final state.
Reconcile BlockPay collections against merchant transaction references.

Note: All values in the request and response examples are dummy data for documentation purposes. Replace them with actual values when making API requests.