Charge a Card (2DS)

This endpoint captures a 2D Secure (2DS) card transaction using server-to-server communication. For Verve cards, this operation is disallowed as per business rules.

Request Parameters

Body (JSON):

• cardNumber: (string, required). The card number of the user.
• expiryYear: (string, required). Expiry year of the card .
• expiryMonth: (string, required). Expiry month of the card.
• cvv: (string, required). The card’s CVV security code.
• amount: (int, required). The transaction amount. (in kobo/cents format e.g "1000" is 10 NGN/USD)
• currency: (string, required). The currency of the transaction (e.g., USD, NGN).
• reference: (string, required). A unique reference for the transaction.
• callbackUrl: (string, required). Callback URL for notifications.
• webhookURL: (string, required)Custom webhook URL for notifications. The webhookUrl must start with http or https to ensure it is a valid URL.
• browserDetails: (optional). Detailed information about the payer's browser. When provided, increase the transaction success rate.
• customer: (optional). Detailed information on the customer making the payment. When provided, it increases the transaction siccess rate

Headers:

• Content-Type: application/json

Responses

200 OK:

• status (int): HTTP status code.
• message (string): Transaction response message.
• data (object): The transaction response data.
• status (object): The authorization status.
• authorizationType (string): Indicates the type of authentication required.
• acsUrl (string): The URL to which the customer must be redirected to complete 3DS authentication.
• reference (string): A unique reference for the transaction, used to track the payment process.
• version (string): Version of 3D Secure being used.
• errors (array): A list of errors, if any.
• paymentRequestor (string): The entity or system initiating the payment request, such as a the merchant.

400 Bad Request: Returned when request parameters are invalid.

Body: JSON object containing the card transaction response.

Endpoint:

POST /transaction/charge

Request Body:

{
    "amount": 10000,
    "email": "[email protected]",
    "currency": "USD",
    "reference": "000045mG7mTL022NzzQ1",
    "callbackUrl": "https://example.com/",
    "webhookUrl": "https://example.com/",
    "cardNumber": "5555555555554444",
    "cvv": "123",
    "expiryYear": 25,
    "expiryMonth": 12,
    "browserDetails": {
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
        "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "language": "en-US",
        "javaEnabled": true,
        "colorDepth": 24,
        "screenHeight": 1080,
        "screenWidth": 1920,
        "timeZone": -60,
        "javaScriptEnabled": true,
        "ipAddress": "192.168.1.1",
        "cardTrustLevel": "FTD"
    },
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "address": {
            "city": "Rome",
            "postcodeZip": "00184",
            "country": "IT",
            "street": "Via Cavour 21"
        }
    }
}

Response (Success):

{
    "status": 200,
    "message": "Request successfully processed",
    "data": {
        "status": 2,
        "authorizationType": "2DS",
        "callbackUrl": "https://merchant.com/callback",
        "akuRef": "pajgYkkiAtfAYc4dg2QC",
        "grossAmount": 100.00,
        "reference": "0f7f209a-8134-437e-a62d-6f38187ad1d6",
        "errorMessage": "Approved",
        "errorCode": "00",
        "paymentRequestor": "Aku Pay Service Ltd",
        "version": "2DS"
    },
    "errors": []
}