NGN ( Bank Transfer )

Creates a BlockPay payment link configured for bank transfer as the payment channel.

The merchant provides the transaction and customer details, while payment_channel is set to BANK_TRANSFER. LedgerBlock returns a hosted payment link that the customer can use to complete the bank transfer.

Endpoint

POST /api/v1/collection/blockpay-link

Authorization

Bearer Token

A valid Bearer Token is required.

Headers

Header	Description	Required
`Authorization`	Bearer token used to authenticate the request	Yes
`x-merchant-ref`	Unique reference identifying the merchant	Yes
`Content-Type`	Specifies that the request body is JSON	Yes

Request Body

Field	Description	Required
`user_ref`	Reference of the user associated with the collection	Yes
`txn_merchant_ref`	Unique transaction reference generated by the merchant	Yes
`amount`	Amount to be collected	Yes
`currency`	Currency of the payment	Yes
`full_name`	Full name of the customer	Yes
`email`	Customer's email address	Yes
`phone`	Customer's phone number	Yes
`chain`	Blockchain network, where applicable	No
`success_message`	Message displayed after a successful payment	No
`payment_method`	Payment method. For BlockPay links, use `BLOCK_PAY_LINK`	Yes
`payment_channel`	Specifies the payment channel. Use `BANK_TRANSFER` for bank transfer payments	Yes
`redirect_url`	URL to redirect the customer after payment	Yes
`notification_url`	URL where transaction notifications should be sent	Yes

Request

curl --location -g '{{base_url}}/api/v1/collection/blockpay-link' \
--header 'Authorization: Bearer <token>' \
--header 'x-merchant-ref: {{vault:x-merchant-ref}}' \
--header 'Content-Type: application/json' \
--data '{
    "user_ref": "USR_TEST_002",
    "txn_merchant_ref": "TXN_TEST_BANK_001",
    "amount": 200,
    "currency": "NGN",
    "full_name": "Test Customer",
    "email": "[email protected]",
    "phone": "08000000001",
    "chain": "",
    "success_message": "Payment successful",
    "payment_method": "BLOCK_PAY_LINK",
    "payment_channel": "BANK_TRANSFER",
    "redirect_url": "https://example.com/payment/success",
    "notification_url": "https://example.com/webhooks/payment"
}'

Response

{
  "status": "success",
  "message": "BlockPay link created successfully",
  "data": {
    "payment_ref": "BPAY-TEST-BANK-001",
    "pay_link": "https://blockpay.example.com/checkout?ref=BPAY-TEST-BANK-001&currency=NGN&amount=200&txn_ref=TXN_TEST_BANK_001",
    "txn_merchant_ref": "TXN_TEST_BANK_001",
    "amount": 200,
    "currency": "NGN",
    "redirect_url": "https://example.com/payment/success",
    "success_message": "Payment successful",
    "pay_data": null
  }
}

Response Fields

Field	Description
`status`	Indicates whether the payment link was created successfully.
`message`	Describes the result of the request.
`data.payment_ref`	Unique payment reference generated for the BlockPay transaction.
`data.pay_link`	Hosted BlockPay checkout URL that can be shared with the customer.
`data.txn_merchant_ref`	Merchant's transaction reference supplied in the request.
`data.amount`	Amount to be collected.
`data.currency`	Currency of the payment.
`data.redirect_url`	URL where the customer is redirected after completing the payment.
`data.success_message`	Message configured to be displayed after successful payment.
`data.pay_data`	Additional payment data. Returns `null` when no additional data is available.

How It Works

The merchant creates a BlockPay payment link.
payment_channel is set to BANK_TRANSFER.
LedgerBlock generates a unique payment reference and hosted payment link.
The merchant shares the pay_link with the customer.
The customer opens the link and completes the bank transfer.
The customer is redirected to the configured redirect_url after payment.
Transaction updates are sent to the configured notification_url.

Use Cases

The Bank Transfer payment link can be used to:

Collect NGN payments through bank transfer.
Generate a hosted payment page for customers.
Provide customers with the information required to complete a bank transfer.
Track payments using a merchant transaction reference.
Receive transaction updates through a notification URL.

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