Create a payment intent

Welcome to the API documentation for the Little Pay API. This API allows you to integrate secure payment processing into your applications. Below, you will find detailed information on how to use the API according to your needs.

To process a payment you must first create a payment intent. This will return a payment intent object that you can use to process a payment.

This endpoint requires Basic Authentication using your merchant's credentials. You'll need to include your clientId and clientSecret in the Authorization header.

Where to get your credentials:

• Access your merchant dashboard at https://pay.little.africa
• Navigate to the Merchants -> Merchant Settings page
• Copy your clientId, clientSecret and tokenId

For detailed step-by-step instructions, see Getting Your API Keys.

How to use Basic Authentication:

• Include an Authorization header with your credentials
• Format: Authorization: Basic {base64(clientId:clientSecret)}
• Most HTTP clients can handle this automatically when you provide the username (clientId) and password (clientSecret)

The key field is a unique alphanumeric string (must not contain special characters) that is used to identify the payment intent. The recommended length is 8-12 characters.

The expiresAt field is an optional field that indicates the number of minutes after which the payment intent will expire. The default is 30 minutes.

The default currency is KES.

You can also provide a callbackUrl that will be called when the payment is completed. The format is specified in Payment Callbacks

The returnUrl is an optional URL that the user will be redirected to after the payment is completed.(Only applicable if using our checkoutUrl)

The metadata.authenticationRedirectUrl is an optional URL that the user will be redirected to after step up authentication (3D Secure) is completed.

Request Payload

Important: While the billing address fields are marked as optional, providing complete and accurate billing address information is strongly recommended for card payments. The billing address is used for Address Verification System (AVS) checks, which can significantly impact payment success rates. Incomplete or incorrect billing address information may lead to payment declines during processing.

Field	Type	Required	Description	Examples
amount	number	Yes	The payment amount in the smallest currency unit (e.g., cents for USD, pence for GBP)	1000 (KES 10.00)
currency	string	No	The currency code (defaults to KES)	"KES", "USD", "EUR"
description	string	Yes	A description of the payment	"Payment for Order #12345"
callbackUrl	string	Yes	URL to be called when payment is completed	"https://yourapp.com/webhooks/payment"
key	string	Yes	Unique alphanumeric identifier for the payment intent (8-12 characters recommended)	"order123", "inv789"
returnUrl	string	No	URL to redirect user after payment completion (only applicable with checkoutUrl)	"https://yourapp.com/success"
expiresAt	number	No	Minutes until payment intent expires (default: 30)	60 (1 hour), 1440 (24 hours)
payload.billingAddress.firstName	string	No	Customer's first name	"John"
payload.billingAddress.lastName	string	No	Customer's last name	"Doe"
payload.billingAddress.address1	string	No	Street address	"123 Main Street"
payload.billingAddress.locality	string	No	City or town	"Nairobi"
payload.billingAddress.administrativeArea	string	No	State, county, or province	"Nairobi County"
payload.billingAddress.postalCode	string	No	Postal or ZIP code	"00100"
payload.billingAddress.country	string	No	ISO two-letter country code	"KE", "US", "GB"
payload.billingAddress.email	string	No*	Customer's email address (either email or phone number is required)	"john.doe@example.com"
payload.billingAddress.phoneNumber	string	No*	Customer's phone number in ISO format (either email or phone number is required)	"+254700000000"
payload.customData	object	No	Any additional JSON data you want to associate with the payment	{"orderId": "12345", "customerType": "premium"}
metadata.authenticationRedirectUrl	string	No	URL to redirect user after 3D Secure authentication	"https://yourapp.com/3ds-callback"

Note: Fields marked with * indicate that at least one of the related fields must be provided. For billing address, you must provide either an email address or a phone number (in ISO format with country code, e.g., +254700000000).

POST /api/payments/{tokenId}/pay

//Loading request body...

Response:

{
  "date": "2024-03-07T13:03:05.141Z",
  "data": {
    "reference": "",
    "checkoutUrl": "",
    "message": "Request processed successfully"
  }
}

The reference is the unique identifier for the payment intent. It is referred to as the intentId in some parts of the documentation.

The checkoutUrl is the URL that you can redirect the user to in order to complete the payment.