Get link

Creates a BlockPay payment link that can be shared with a customer to complete a payment.

The merchant specifies the amount, currency, customer details, and payment configuration. LedgerBlock returns a unique payment reference and a hosted checkout link.

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

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
`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_001",
    "txn_merchant_ref": "TXN_TEST_BP_001",
    "amount": 250,
    "currency": "NGN",
    "full_name": "Test Customer",
    "email": "[email protected]",
    "phone": "08000000000",
    "chain": "",
    "success_message": "Payment successful",
    "payment_method": "BLOCK_PAY_LINK",
    "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-001",
    "pay_link": "https://blockpay.example.com/checkout?ref=BPAY-TEST-001&currency=NGN&amount=250&txn_ref=TXN_TEST_BP_001",
    "txn_merchant_ref": "TXN_TEST_BP_001",
    "amount": 250,
    "currency": "NGN",
    "redirect_url": "https://example.com/payment/success",
    "success_message": "Payment successful",
    "pay_data": null
  }
}

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.