L2 Payment API Documentation

Overview

This document provides the required fields and specifications for Level 2 (L2) payment processing using the VPC payment processor. L2 processing provides enhanced data for commercial and corporate card transactions.

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)

Bill To Object (billTo)

Example Request

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: f63e6ab9-6f3f-4081-ab45-9a941f8e1344' \
--data-raw '{
    "merchantId": "855500000027",
    "terminalId": "48593451",
    "paymentType": "sale",
    "commerceIndicator": "moto",
    "amount": "100",
    "level": "2",
    "cardData": {
        "panNumber": "4111111111111111",
        "expiryDate": "1231",
        "cvv": "999"
    },
    "invoiceDetails": {
        "purchaseOrderNumber": "1000010"
    },
    "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: f63e6ab9-6f3f-4081-ab45-9a941f8e1344' \
--data-raw '{
    "merchantId": "855500000027",
    "terminalId": "48593451",
    "paymentType": "auth",
    "commerceIndicator": "moto",
    "amount": "100",
    "level": "2",
    "cardData": {
        "panNumber": "4111111111111111",
        "expiryDate": "1231",
        "cvv": "999"
    },
    "invoiceDetails": {
        "purchaseOrderNumber": "1000010"
    },
    "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: f63e6ab9-6f3f-4081-ab45-9a941f8e1344' \
--data-raw '{
    "merchantId": "855500000027",
    "terminalId": "48593451",
    "paymentType": "refund",
    "commerceIndicator": "moto"
    "amount": "100",
    "level": "2",
    "cardData": {
        "panNumber": "4111111111111111",
        "expiryDate": "1231"
    },
    "invoiceDetails": {
        "purchaseOrderNumber": "1000010"
    },
    "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

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 2 Processing: Set level to "2" for enhanced commercial card processing
2. Field Validation: All L2 required fields must be present and properly formatted
3. Purchase Order: Critical for L2 - must be exactly 17 characters or less, alphanumeric only
4. Customer Information: Names should match cardholder information for best processing rates
5. Environment: Use sandbox URL for testing, production URL will be provided separately

Error Handling

Common validation errors for L2 transactions:

• Missing required L2 fields (billTo, invoiceDetails)
• Invalid purchaseOrderNumber format or length
• Invalid email format
• Missing or invalid level field

Support

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