Pay by Card

Collecting card payments in Naira (NGN) and Pounds (GBP) allows you to accept payments from customers globally using our Direct API. This process gives you full control over your checkout UI while Leatherback handles the complex communication with card schemes and issuing banks.

You can collect card payments in three easy steps:

Initiate Payment: Submit transaction, customer, and card details.
Verify Status: Confirm the final state of the transaction.

📘
Before you begin!
To collect payments, you need your API keys. You can find these on the Fusion Dashboard under Settings → API Keys. Follow this guide.
All requests must be authenticated using your Secret Key in the header.

Initiate the Payment

To start the transaction, make a POST request to the Initiate Payment API. This request combines the transaction amount, customer information, and raw card details.

curl --request POST \
     --url https://laas.leatherback.co/api/payment/pay/initiate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
    "amount": 1,
    "channel": "Card",
    "currency": "GBP",
    "narration": "--", // Optional
    "link": {
        "alias": "0-k2tmbuy"
    }, // Only Required if payment is for a payment link
    "userInformation": {
        "firstName": "Dave",
        "lastName": "MC",
        "emailAddress": "[email protected]",
        "phone": "070 0000 0000"
    },
    "paymentRequestProps": {
        "card": {
            "cvv": "123",
            "expMonth": 6,
            "expYear": 2025,
            "number": "4242424242424242"
        },
        "returnUrl": "string" //required (For GBP)
    },
    "metaData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'

{
  "value": {
    "paymentStatus": "INITIATED",
    "message": "Payment Initiated Successfully",
    "bankAuthURL": null,
    "paymentItem": {
      "channel": "Card",
      "message": "Payment Initiated Successfully",
      "amount": 1,
      "fees": 0,
      "reference": "THGUJYNHACLVSPG",
      "paymentReference": "THGUJYNHACLVSPG",
      "metaData": {}
    }
  },
  "isSuccess": true
}

💡
Pro Tip: Managing the UI
If you are loading the AuthUrl in an iFrame or a modal and want the window to close automatically once validated, locate the redirect=true parameter in the URL and change it to redirect=false before loading it for the user.

Verify Transaction Status

Once the customer has completed authentication, you must verify the final status of the transaction.

While Webhooks are recommended for production systems, you can also use polling.

Verify via Polling

Call the Get Transaction Status API using the paymentReference returned in the initiation step.

Status Meanings

Status	Meaning	Action Required
SUCCESSFUL	The funds have been secured	Provide value or services to customer
PENDING	User has authorized; awaiting bank settlement	Display "Processing" screen
FAILED	The charge was rejected	Prompt user for another payment method

{
  "value": {
    "paymentReference": "TVI1HLDDNATWSPG",
    "amount": {
      "currencyCode": "NGN",
      "amount": 100
    },
    "paymentStatus": "Successfull"
  },
  "isSuccess": true
}

Listen for Status (Webhooks)

To avoid the overhead of polling, ensure your Webhook URL is configured in the Developer Portal. See guide here.

We will push a POST notification to your server the moment a transaction is finalized.

Webhook Events

payment.success – Trigger your fulfillment logic
payment.failed – Notify the user and log the failure reason