Server to Server (Cards)

Here is a quick overview of how to integrate BudPay's Server to Server (Direct Charge API) for card payments:

1. Collect Customer Information: Collect the customer's card details securely within your application.
2. Card Encryption: Encrypt the card details using aes-128-cbc encryption algorithm.
3. Initialize Transaction: Send the encrypted card details to S2S initialize endpoint to initialize the transaction.
4. 3DS Authentication: If the card requires 3D Secure verification, we will return a URL to redirect the customer to complete the verification.
5. Verify Transaction: After the customer completes the 3D Secure verification, you can verify the transaction using the verify endpoint.

Step1: Collect Customer Information

Collect the customer's card details securely within your application. Ensure that you are compliant with PCI DSS standards when handling card information. Here is an example of the card details you need to collect:

{
  "data": {
    "number": "4242424242424242",
    "cvv": "123",
    "expiryMonth": "12",
    "expiryYear": "28",
    "pin": "1234" // optional - only required for verve/local cards
  },
  "reference": "1234567890"
}

1. number The customer's card number.
2. cvv The card verification value (CVV) on the back of the card.
3. expiryMonth The card's expiry month (2 digits).
4. expiryYear The card's expiry year (2 digits, e.g. "28" for 2028).
5. reference A unique reference for the transaction.

Step2: Card Encryption

Encrypt the card details using the aes-256-cbc encryption algorithm. Here is an example to do this:

Encryption Parameters

This section describes the parameters required for the encryption function:

const crypto = require('crypto');
 
function cardEncryption() {
    const data = {
        number: "5123450000000008",  // Card Number
        expiryMonth: "10",           // Card Expiry Month
        expiryYear: "28",            // Card Expiry Year
        cvv: "100",                  // Card CVV
        pin: "1234"                  // (Optional - only required for verve/local cards)
    };
    
    const key = 'BUDPAY_PUBLIC_KEY'; // Encryption Key: BudPay Public key used for encryption
    const reference = "10033333333333333";  // 16 Digits Minimum
    
    const iv = reference.slice(0, 16);      // Initialization Vector: A fixed-size input for the cryptographic algorithm to ensure uniqueness
    const encryptionType = 'aes-256-cbc';   // Encryption Type: Specifies the encryption algorithm and mode
 
    // Convert key to Buffer for crypto library
    const keyBuffer = Buffer.from(key, 'utf-8');
 
    // Convert iv to Buffer for crypto library
    const ivBuffer = Buffer.from(iv, 'utf-8');
 
    // Create a Cipher object
    const cipher = crypto.createCipheriv(encryptionType, keyBuffer, ivBuffer);
 
    // Encrypt the data
    let encryptedData = cipher.update(JSON.stringify(data), 'utf-8', 'hex');
    encryptedData += cipher.final('hex');
 
    return encryptedData;
}
 
console.log(cardEncryption());

This function cardEncryption encrypts the card details using AES-256-CBC encryption and returns the encrypted data as a hexadecimal string.

Test Encryption Endpoint

We provided a test encryption endpoint to help you encrypt your card details. The purpose of this test endpoint is to help you confirm that you are encrypting the card details correctly in your codebase before sending them to the S2S initialize endpoint.

Test Encryption Parameters

This section describes the parameters required for the encryption endpoint:

curl 
-X POST https://api.budpay.com/api/s2s/test/encryption
-H "Content-Type: application/json"
-H "Authorization: Bearer YOUR_SECRET_KEY"
-d '{
    "data": {
        "number": "4242424242424242",
        "cvv": "123",
        "expiryMonth": "12",
        "expiryYear": "28",
        "pin": "1234"
    },
    "reference": "1234567890"
}'

Test Card Encryption Response

The response will contain the encrypted card details. Here is an example response:

{
    "card": "83fa6763bb31bae36a74f787ab814514aeede91fcdb311fd67609b414c5e5ea2751a47870c8717e71bcbc9c33287a3d6af9ffae8e2edbf2de1e2694384d699b020d31492637eef60d7a63f303798363a"
}

Try it out

Step3: Initialize Transaction

Send the encrypted card details to the S2S initialize endpoint to initialize the transaction. Here is an example of the request body:

Initialize Transaction Example

curl https://api.budpay.com/api/s2s/transaction/initialize
-H "Authorization: Bearer YOUR_SECRET_KEY"
-H "Content-Type: application/json"
-d '{ 
    "amount": "100", 
    "card" :"83fa6763bb31bae36a74f787ab814514aeede91fcdb311fd67609b414c5e5ea2751a47870c8717e71bcbc9c33287a3d6af9ffae8e2edbf2de1e2694384d699b020d31492637eef60d7a63f303798363a", 
    "currency": "USD", 
    "email": "test@email.com", 
    "reference": "1253627873656276350" 
}'
-X POST

Initialize Transaction Request Payload

{
  "card": "83fa6763bb31bae36a74f787ab814514aeede91fcdb311fd67609b414c5e5ea2751a47870c8717e71bcbc9c33287a3d6af9ffae8e2edbf2de1e2694384d699b020d31492637eef60d7a63f303798363a",
  "pin": "1234", // optional - only required for verve/local cards
  "amount": 10000,
  "currency": "NGN",
  "email": "test@gmail.com",
  "callback": "https://yourwebsite.com/callback",
  "reference": "1234567890"
}

Try it out

Initialize Transaction Parameters

This section describes the parameters required for the initialize transaction:

Step4: 3DS Authentication

If the card requires 3D Secure verification, we will return a URL to redirect the customer to complete the verification. Here is an example of the response:

3DS Authentication Response

{
    "status": true,
    "message": "Proceed authentication 3DS2",
    "data": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://secure-acs2ui-b1.wibmo.com/v1/acs/services/threeDSMethod/8528?cardType=M\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9ldS5nYXRld2F5Lm1hc3RlcmNhcmQuY29tL2NhbGxiYWNrSW50ZXJmYWNlL2dhdGV3YXkvOGFkZGRiNzE1MTQwMjk2OWMxMmI1Y2QzNjBhOTdmYTdiZTE1ZWU1NWZiZDEwZTE5MmI3ZDIwNDcxNmQxYTVlNSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiZjgxNGM3YWMtMmRiOS00Nzg1LThhMjYtYjA2NjZlYTBjMGVkIn0=\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
    "_links": {
        "url": "http://api.budpay.com/api/mastercard-payment/3ds2auth",
        "method": "POST",
        "payload": [
            "ref"
        ]
    }
}

You are required to open the 3DS2 Response data html in a hidden page to run in background for 20 seconds and then hit the _links endpoint in the response to proceed. After that you will get the final response.

3DS2 Flow Diagram

Final Response

If the card does not require 3D Secure verification, you will receive the final response. Here is an example of the response:

Final Response Example (mastercard and visa)

{
    "status": "success",
    "message": "Approved or Captured"
}

Final Response Example (verve)

{
    "status": true,
    "message": "Payment Successful"
}

Verifying Transactions

Call the Verify Transaction API with the transaction reference:

GET https://api.budpay.com/api/v2/transaction/verify/:reference

Example Request:

curl https://api.budpay.com/api/v2/transaction/verify/BUD_1673600359168063493 \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -X GET

Example Response:

{
  "status": true,
  "message": "Transaction verified successfully",
  "data": {
    "currency": "NGN",
    "amount": "550",
    "reference": "BUD_1673600359168063493",
    "status": "success",
    "message": "Payment successful",
    "customer": {
      "email": "customer@email.com"
    }
  }
}

Verification Workflow:

1. Receive callback/webhook with transaction reference
2. Call Verify API (server-side)
3. Check status === "success"
4. Verify amount matches expected
5. Fulfill order/deliver service

Learn more about verifying transactions.

Testing Your Integration

BudPay provides a comprehensive sandbox environment for testing:

Test Card Numbers:

Test Mobile Money Numbers:

• Kenya (M-Pesa): 254712345678
• Ghana (MTN): 233244000000