Payment Link Integration
The Payment Link Integration flow allows you to programmatically generate secure, hosted payment pages for your customers. Instead of building a custom checkout UI, you can generate a link, redirect your customer to it, and let Leatherback handle the complexities of payment processing.
Integration Lifecycle:
- From your server, call our
Create Payment link,Validate Payment link,Initiate the payment linkendpoints with the payment details. - We'll return a link alias to a payment page. Redirect your customer to this link to make the payment.
- Aunthenticate card transaction (optional).
- Finalise the transaction.
- When the transaction is completed, we'll redirect the customer back to you.
Integration Flow
Step 1: Create a Payment Link
First, generate the link on your server through a POST request to the Create Payment Link API. You can specify if the link is for a specific invoice (One-Time) or if it can be reused for multiple payments (Reusable).
curl --request POST \
--url https://laas.leatherback.co/api/payment/payment-link \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"name": "Invoice Test 5",
"description": "Test",
"linkType": 1,
"amountType": 1,
"currencyCode": "GBP",
"amountInfo": {
"currencyCode": "GBP",
"amount": 12
"linkType": 0 - oneTime, 1 - reusable
"amountType": 0 - Static, 1 - Dynamic
}
}'{
"value": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Nike Air",
"description": "Payment For Nike Air - INV100000000",
"alias": "0-k2tmbuy",
"link": "https://app-aaaspaymentlink-stg.azurewebsites.net/0-k2tmbuy",
"amountInfo": {
"currencyCode": "NGN",
"amount": 100
},
"linkType": "OneTime",
"status": "New",
"createdDate": "2023-03-31T10:43:09.1931541+00:00",
"environment": "Test"
},
"isSuccess": true,
"message": "Request Successful"
}{
"value": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Nike Air",
"description": "Payment For Nike Air - INV100000000",
"alias": "0-k2tmbuy",
"link": "https://app-aaaspaymentlink-stg.azurewebsites.net/0-k2tmbuy",
"amountInfo": {
"currencyCode": "NGN",
"amount": 100
},
"linkType": "Reuseable",
"status": "New",
"createdDate": "2023-03-31T10:43:09.1931541+00:00",
"environment": "Test"
},
"isSuccess": true,
"message": "Request Successful"
}Step 2: Validate Available Channels
Before the customer pays, you need to know which payment methods are active for their currency. This ensures you only show valid options, like Interac for CAD or Bank Transfer for NGN. Call the Validate Payment Request API with a POST request.
curl --request POST \
--url https://laas.leatherback.co/api/payment/pay/validate \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"amount": {
"currencyCode": "GBP",
"amount": 10
},
"channels": [
"card"
]
}
'{
"value": {
"isValid": true,
"channels": [
{
"id": "9a69343e-c18d-4aeb-a0a2-0995b44596dc",
"name": "Card",
"alias": "Card",
"description": null
},
{
"id": "6bdaf37f-9518-44d6-aa79-fafb382aa5c7",
"name": "PayByAccount",
"alias": "PayByAccount",
"description": null
}
]
},
"isSuccess": true,
"error": "",
"message": "Request Successful",
"type": null,
"title": null,
"status": null,
"detail": null,
"instance": null
}If No channel is passed in the request, the response returned will be based on the eligible channels on your account
Step 3: Initiate the Payment
Once a customer selects a channel, you initiate the payment by sending their details, currency and the reference ID from the previous step to the Initiate Payment Request API in a POST request.
curl --request POST \
--url https://laas.leatherback.co/api/payment/pay/initiate \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"amount": 100,
"channel": "PayByTransfer",
"currency": "NGN",
"link": {
"alias": "0-k2tmbuy"
}, // Only Required if payment is for a payment link
"userInformation": {
"firstName": "Dave",
"lastName": "MC",
"emailAddress": "[email protected]",
"phone": "0901 010 1010"
}
}'{
"value": {
"paymentStatus": "REQUIRE_USER_OFFLINE_ACTION",
"message": "Payment Initiated",
"bankAuthURL": null,
"paymentItem": {
"channel": "PayByTransfer",
"message": "Payment Initiated",
"amount": 500,
"fees": 0,
"reference": "4f737265-27cb-40fd-84a6-f41d999a39d1",
"metaData": {
"transfer-info": {
"note": "NILL",
"bank": "Providus",
"account_number": "9979314914",
"account_name": "MERCHANT(jkkffg)",
"expiration": "2023-03-04T13:43:11.0447022Z",
"mode": "banktransfer"
}
}
}
},
"isSuccess": true,
"error": "",
"message": "",
"type": null,
"title": null,
"status": null,
"detail": null,
"instance": null
}Optional: Authenticate the Transaction
For card payments, security standards often require 3D Secure (3DS) authentication to verify the cardholder's identity. This endpoint allows you to check if a specific transaction requires an extra layer of authorization—such as an OTP or a hardware token—before it can be completed.
By calling this endpoint, you determine whether to present an authentication challenge to your customer.
To verify if authentication is needed, make a GET request to the Authenticate Payment API using the referenceId generated during the Initiation step.
{
"referenceId": "4f737265-27cb-40fd-84a6-f41d999a39d1"
}{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"isSuccess": true,
"error": "string",
"message": "string",
"responseCode": "string",
"value": {
"status": "string",
"IsAuthenticationEnabled": true,
"Recommendation": "string",
"message": "string",
"authenticationhtml": "string"
},
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}Finalize the Payment
Once the customer has completed any required authorization steps, such as 3D Secure for cards, you must call the Finalize Payment Request API. This step signals to the Leatherback engine that the user's part of the transaction is complete and the funds should be reconciled and moved to your settlement account.
To finalize the payment, make a POST request using the paymentReference. This reference is the unique identifier for the specific payment attempt you received during the Validation phase.
curl --request POST \
--url https://laas.leatherback.co/api/payment/pay/finalize \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"paymentReference": "string"
}
'{
"type": "https://api.yourdomain.com/errors/example",
"title": "Request processed successfully",
"status": 200,
"detail": "The operation completed without errors.",
"instance": "/api/v1/resource/123",
"isSuccess": true,
"error": null,
"message": "Success",
"responseCode": "00",
"value": {
"status": "completed",
"message": "Resource created successfully"
}
}Verify Transaction Status
Once a transaction has been initiated or finalized, you may need to manually verify its state. This allows you to retrieve the current lifecycle status of a payment using its unique reference ID.
While we recommend relying on Webhooks for automated fulfillment, this step is essential for manual reconciliation, polling (if necessary), or handling "Success" redirects on your frontend.
Verify via Polling
Call the Get Transaction Status API and pass the reference as a path variable. This is the reference ID you received during the Initiation step.
{
"value": {
"paymentReference": "TVI1HLDDNATWSPG",
"amount": {
"currencyCode": "NGN",
"amount": 100
},
"paymentStatus": "Successfull"
},
"isSuccess": true
}After the payment is initiated and completed successfully: We'll send you a webhook if you have that configured on the Fusion dashboard. We'll send an email receipt to your customer if the payment was successful (coming soon)