Initiate Card Payments

This endpoint initiates a card payment through LedgerBlock using encrypted card data. The response includes an authorization token and payment reference, which are used to continue the payment authentication process.

Request

POST {{base_url}}/api/v1/collection/ledgerblock/card/initiate

Authentication

LedgerBlock uses Bearer Token authentication. Include your API key in the Authorization header.

ParameterValueType
Authorization{{api_key}}Bearer Token

Headers

HeaderRequiredDescriptionExample
Content-TypeYesSpecifies that the request body is JSON.application/json
x-merchant-refYesUnique reference identifying the merchant.{{vault:x-merchant-ref}}

Example Request

{
  "user_ref": "DUMMY_USER_REF_001",
  "card_data": "{{encrypted_card_data}}",
  "customer_name": "Test Customer",
  "customer_email": "[email protected]",
  "customer_address": {
    "postal_code": "100001",
    "country_code": "NG",
    "city": "Lagos",
    "line1": "10 Example Street",
    "state": "LAGOS"
  },
  "country_code": "NG",
  "customer_phone": "2348000000000",
  "amount": 400,
  "currency": "NGN",
  "narration": "Card collection",
  "txn_ref": "DUMMY_CARD_TXN_001",
  "redirect_url": "https://example.com/payment/callback"
}

Example Response

{
  "status": "processing",
  "message": "Payment processing",
  "data": {
    "auth_token": "{{auth_token}}",
    "payment_ref": "DUMMY-PAYMENT-REF-001",
    "complete_pay_method": "",
    "redirect_url": "",
    "payment_status": "processing"
  }
}

Response Parameters

FieldDescription
statusIndicates the current response status.
messageProvides information about the payment initiation result.
data.auth_tokenAuthorization token used to continue the card payment session. The session has a validity of one hour.
data.payment_refUnique LedgerBlock reference assigned to the card transaction.
data.complete_pay_methodIndicates the payment authentication method required to complete the transaction. It may initially be empty.
data.redirect_urlURL used to redirect the customer when applicable. It may initially be empty.
data.payment_statusCurrent status of the payment. processing indicates that the payment flow has been initiated.

Completing the Card Payment

After initiating the payment, the customer can complete the required authentication using one of the supported methods:

MethodDescription
OTPThe customer verifies the transaction using a one-time password.
PINThe customer provides the required card PIN.
3DSThe customer completes the card issuer's 3D Secure authentication flow.

The authentication method required depends on the payment flow. Use the returned auth_token and payment_ref as required by the corresponding completion endpoint.


Did this page help you?