Charge a Card (3DS)

This process initializes a 3D Secure (3DS) transaction, requiring user authentication via redirection and it involves two main steps:

1. Initialize the Payment: Start the payment process and redirect the customer to the ACS (Access Control Server) for 3DS authentication.
2. Verify the Payment: Confirm the payment status after the customer completes the 3DS authentication.

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)
• email: (string, required) The email address of the customer/cardholder
• 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 3DS route.
• sourceUrl: (string, optional). The originating URL.
• 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 success rate
• Terminal ID (TID): (optional). Uniquely identifies a specific payment terminal, virtual endpoint, or logical channel under a merchant account (MID)

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/",
    "sourceUrl": "https//sourceexample.com",
    "cardNumber": "5555555555554444",
    "tid": "TT9GMG",
    "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": "Jane",
        "lastName": "Doe",
        "address": {
            "city": "Rome",
            "postcodeZip": "00184",
            "country": "IT",
            "street": "Via Cavour 21",
            "stateProvinceCode": "DE"
        }
    }
}

Response (Success):

{
    "status": 200,
    "message": "Request successfully processed",
    "data": {
        "status": 200,
        "authorizationType": "3DS",
        "acsUrl": "https://test-gateway.akupay.africa/acs/CaW8K1xydcE5v24f_xEt",
        "reference": "CaW8K1xydcE5v24f_xEt",
        "paymentRequestor": "Merchant Limited",
        "version": "3DS2"
    },
    "errors": []
}

Example Error Responses:

Webhook URL

If the webhookUrl is invalid (e.g., does not start with http or https), the system will reject the request with an error message:

{  
  "status": 400,  
  "message": "Invalid webhook URL. The URL must start with 'http' or 'https'."  
}

Note:

Merchant must redirect the user to acsUrl for 3DS authentication. Upon completion, the user is redirected to the callback URL with the transactionReference, status, errorMessage and reference.

Error Responses: