L3 Payment API Documentation

Overview

This document provides the required fields and specifications for Level 3 (L3) payment processing using the VPC payment processor. L3 processing provides the most detailed transaction data for commercial and corporate card transactions, including line-item details.

Base URL

Sandbox Environment: https://apitest.valorvpc.com

Authentication

All requests require the X-App-Key header with your merchant's App Key obtained during merchant boarding.

Common Required Headers

Content-Type: application/json
X-App-Key: {your-app-key}

Sale Transaction

Endpoint

POST https://apitest.valorvpc.com/payment/sale

Required Fields

Card Data Object (cardData)

Invoice Details Object (invoiceDetails)

Line Items Array (lineItems)

Bill To Object (billTo)

Example Request

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: 058e55b0-8b96-4609-9316-aa97e4a22679' \
--data-raw '{
    "merchantId": "855500000027",
    "terminalId": "48593451",
    "paymentType": "sale",
    "commerceIndicator": "moto",
    "amount": "100",
    "level": "3",
    "cardData": {
        "panNumber": "4111111111111111",
        "expiryDate": "1231",
        "cvv": "999"
    },
    "invoiceDetails": {
        "purchaseOrderNumber": "1000010"
    },
    "lineItems": [
        {
            "unitPrice": "100.00",
            "taxAmount": "0.00"
        }
    ],
    "billTo": {
        "firstName": "Artan",
        "lastName": "Merko",
        "email": "[email protected]"
    }
}'

Authorization Transaction

Endpoint

POST https://apitest.valorvpc.com/payment/auth

Required Fields

Same as Sale transaction, but with paymentType set to "auth".

Example Request

curl --location 'https://apitest.valorvpc.com/payment/auth' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: 058e55b0-8b96-4609-9316-aa97e4a22679' \
--data-raw '{
    "merchantId": "855500000027",
    "terminalId": "48593451",
    "paymentType": "auth",
    "commerceIndicator": "moto",
    "amount": "100",
    "level": "3",
    "cardData": {
        "panNumber": "4111111111111111",
        "expiryDate": "1231",
        "cvv": "999"
    },
    "invoiceDetails": {
        "purchaseOrderNumber": "1000010"
    },
    "lineItems": [
        {
            "unitPrice": "100.00",
            "taxAmount": "0"
        }
    ],
    "billTo": {
        "firstName": "Artan",
        "lastName": "Merko",
        "email": "[email protected]"
    }
}'

Direct Refund Transaction

Endpoint

POST https://apitest.valorvpc.com/payment/refund

Required Fields

Same as Sale transaction, but with paymentType set to "refund" and CVV is optional.

Example Request

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: 058e55b0-8b96-4609-9316-aa97e4a22679' \
--data-raw '{
    "merchantId": "855500000027",
    "terminalId": "48593451",
    "paymentType": "refund",
    "commerceIndicator": "moto",
    "amount": "100",
    "level": "3",
    "cardData": {
        "panNumber": "4111111111111111",
        "expiryDate": "1231"
    },
    "invoiceDetails": {
        "purchaseOrderNumber": "1000010"
    },
    "lineItems": [
        {
            "unitPrice": "100.00",
            "taxAmount": "0"
        }
    ],
    "billTo": {
        "firstName": "Artan",
        "lastName": "Merko",
        "email": "[email protected]"
    }
}'

Field Specifications

Purchase Order Number (invoiceDetails.purchaseOrderNumber)

• Format: Alphanumeric characters only
• Restrictions: No hyphens, spaces, or special characters
• Maximum Length: 17 characters
• Important: Requests with 18+ characters will fail

Line Items (lineItems)

• Required for L3: Must include at least one line item
• unitPrice: Required, numeric format (e.g., "100.00")
• taxAmount: Required, numeric format, can be "0" or "0.00" if no tax
• unitOfMeasure: Optional, alphanumeric string, max 12 characters, cannot be all zeros
• commodityCode: Optional, alphanumeric only (no hyphens, spaces, or symbols), max 12 characters
• Important: unitPrice and taxAmount must be present even if tax is zero

Customer Name (billTo.firstName and billTo.lastName)

• Purpose: Customer identification
• Requirement: Must match the name on the card
• Maximum Length: 60 characters each
• Format: String

Email Address (billTo.email)

• Purpose: Customer contact information
• Format: Valid email address including full domain name
• Maximum Length: 255 characters
• Example: [email protected]

Response Format

Success Response

{
  "responseCode": "00",
  "ref_id": "unique-transaction-id",
  "status": "AUTHORIZED",
  "processorInformation": {
    "approvalCode": "123456",
    "retrievalReferenceNumber": "123456789012"
  }
}

Error Response

{
  "error": {
    "status": "INVALID_REQUEST",
    "reason": "MISSING_FIELD",
    "message": "Required field missing"
  }
}

Important Notes

1. Level 3 Processing: Set level to "3" for enhanced commercial card processing with line-item details
2. Line Items Required: L3 transactions must include lineItems array with unitPrice and taxAmount
3. Tax Amount: Must be provided even if zero (use "0" or "0.00")
4. All L2 Requirements: L3 includes all L2 requirements plus line-item details
5. Field Validation: All L3 required fields must be present and properly formatted
6. Environment: Use sandbox URL for testing, production URL will be provided separately

Error Handling

Common validation errors for L3 transactions:

• Missing required L3 fields (lineItems, billTo, invoiceDetails)
• Missing unitPrice or taxAmount in line items
• Invalid purchaseOrderNumber format or length
• Invalid email format
• Missing or invalid level field

Support

For technical support or questions about L3 processing requirements, contact the VPC development team.