PCI DSS required
Using this endpoint involves dealing with cardholder Personally Identifying Information (PII). A Payment Card Industry Data Security Standard (PCI DSS) certificate is therefore required.
This endpoint allows you to request a payment from customers by charging their debit/credit cards.
You send the customer details along with the card and billing information.
Request
The request payload would be encrypted. Please follow the guide here.
The parameters you can use to build the request payload are given below:
| Param | Required? | Description |
|---|---|---|
| Yes | Email address of customer | |
| reference | Yes | Unique case sensitive reference. Only -, ., _, and alphanumeric characters allowed |
| amount | Yes | Amount the customer is to pay. This can include decimals (i.e. 10.75) |
| currency | Yes | ISO 3-Letter Currency Code e.g. ZMW, USD |
| bearer | No | Decide who will bear the fee. Either merchant (you), or customer (your customer).Note: This will only be used if not already set in your dashboard. |
| customer | Yes | This field holds the customer details |
| customer.firstName | Yes | The first name of the customer |
| customer.lastName | Yes | The last name of the customer |
| billing | Yes | This field holds the customer's billing address |
| billing.streetAddress | Yes | The street address |
| billing.city | Yes | The city |
| billing.state | No | The state or province. If a country does not have states or provinces, this can be left blank. Note: For US states and Canada provinces, this should be the 2-letter code for the state / province. i.e. California should be CA.You can find the list of US State and Canada Province codes here |
| billing.postalCode | Yes | The postal code |
| billing.country | Yes | 2-letter code i.e. United states should be US.You can find the list of country codes here |
| card | Yes | This field holds the card details |
| card.number | Yes | Card PAN |
| card.expiryMonth | Yes | Card expiry month |
| card.expiryYear | Yes | Card expiry year |
| card.cvv | Yes | Card security code |
| redirectUrl | No | The customer will be redirected to this url after completing the payment. Your reference, lencoReference, status, and an optional errorMessage will be appended as query parameters to the redirectUrl |
// Sample payload to be encrypted
{
"reference": "test-1",
"email": "customer@email.com",
"amount": "1000",
"currency": "ZMW",
"bearer": "merchant",
"customer": {
"firstName": "John",
"lastName": "Doe"
},
"billing": {
"streetAddress": "901 metro center blvd",
"city": "San Francisco",
"state": "CA",
"postalCode": "94404",
"country": "US"
},
"card": {
"number": "5555 5555 5555 4444",
"cvv": "838",
"expiryMonth": "12",
"expiryYear": "2024"
},
"redirectUrl": "https://www.yoururl.com/verify_payment"
}
Response
For cards that require 3D Secure authorization, the value of data.status would be "3ds-auth-required" and the response would include an authorization object in the meta key.
This authorization object would contain a mode key which will be "redirect", and a redirect key.
You should redirect your customer to the URL specified in meta.authorization.redirect to complete the 3DS authorization.
// Response Schema
{
"status": boolean,
"message": string,
"data": {
"id": string,
"initiatedAt": date-time,
"completedAt": date-time | null,
"amount": string,
"fee": string | null,
"bearer": "merchant" | "customer",
"currency": string,
"reference": string,
"lencoReference": string,
"type": "card",
"status": "pending" | "successful" | "failed" | "3ds-auth-required",
"source": "api",
"reasonForFailure": string | null,
"settlementStatus": "pending" | "settled" | null,
"settlement": null,
"mobileMoneyDetails": null,
"bankAccountDetails": null,
"cardDetails": {
"firstName": string | null,
"lastName": string | null,
"bin": string | null,
"last4": string | null,
"cardType": string | null,
} | null,
"meta": { // optional
"authorization": {
"mode": "redirect",
"redirect": string
}
}
}
}
You can use any of the cards listed here to test card collections in the sandbox environment