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.
| Parameter | Value | Type |
|---|---|---|
| Authorization | {{api_key}} | Bearer Token |
Headers
| Header | Required | Description | Example |
|---|---|---|---|
Content-Type | Yes | Specifies that the request body is JSON. | application/json |
x-merchant-ref | Yes | Unique 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
| Field | Description |
|---|---|
status | Indicates the current response status. |
message | Provides information about the payment initiation result. |
data.auth_token | Authorization token used to continue the card payment session. The session has a validity of one hour. |
data.payment_ref | Unique LedgerBlock reference assigned to the card transaction. |
data.complete_pay_method | Indicates the payment authentication method required to complete the transaction. It may initially be empty. |
data.redirect_url | URL used to redirect the customer when applicable. It may initially be empty. |
data.payment_status | Current 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:
| Method | Description |
|---|---|
| OTP | The customer verifies the transaction using a one-time password. |
| PIN | The customer provides the required card PIN. |
| 3DS | The 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.
Updated about 1 month ago
Did this page help you?
