PIN Debit Payment

Overview

This guide covers PIN Debit payment processing for retail transactions.

Common Requirements

All PIN Debit transactions must include:

merchantId: Merchant identifier
terminalId: Terminal identifier
paymentType: Transaction type (sale, refund, balance_inquiry)
amount: Transaction amount in USD (e.g., "100" or "100.00") - not required for balance inquiry
entryMode: Card entry method (contactless, contact, swiped)
card: Set to "debit" for PIN Debit transactions
commerceIndicator: Set to "retail" for in-person transactions
cardData: Card information (EMV or track data)

Authentication: All requests require X-App-Key header for API authentication.

PIN Debit Sale Transactions

1. Contactless Sale

Entry Mode: Contactless (NFC/tap payment)

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "amount": "100",
  "entryMode": "contactless",
  "card": "debit",
  "pin_block": "5D5FA5E5B448F33B",
  "pin_format": "0",
  "ksn": "FFFF1B1D140000200001",
  "commerceIndicator": "retail",
  "cardData": 
    { "emvData":
      { "tags":
              "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
              "trackData": ";4111111111111111=33121019761186800000?",
              "cardSequenceNumber": "01"
      }
    }
  }'

2. Contact Sale (Chip Insert)

Entry Mode: Contact (chip card inserted into reader)

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "amount": "100",
  "commerceIndicator": "retail",
  "entryMode": "contact",
  "card": "debit",
  "pin_block": "5D5FA5E5B448F33B",
  "pin_format": "0",
  "ksn": "FFFF1B1D140000200001",
  "cardData": {
    "emvData": {
      "tags": "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
      "trackData": ";4111111111111111=33121019761186800000?",
       "cardSequenceNumber": "01"

    }
  }
}'

3. Swiped Sale (Magnetic Stripe)

Entry Mode: Swiped (magnetic stripe read)

curl --location 'https://apitest.valorvpc.com/payment/sale' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "sale",
  "amount": "100",
  "commerceIndicator": "retail",
  "entryMode": "swiped",
  "card": "debit",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "trackData": ";4111111111111111=33121019761186800000?"
  }
}'

PIN Debit Refund Transactions

Direct refunds return funds to a debit card without referencing a previous transaction. All entry modes are supported.

1. Swiped Refund

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "refund",
  "commerceIndicator": "retail",
  "card": "debit",
  "amount": "100",
  "entryMode": "swiped",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "trackData": ";4111111111111111=33121019761186800000?"
  }
}'

2. Contact Refund

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "refund",
  "card": "debit",
  "commerceIndicator": "retail",
  "amount": "100.00",
  "entryMode": "contact",
  "pin_block": "5D5FA5E5B448F33B",
  "pin_format": "0",
  "ksn": "FFFF1B1D140000200001",
  "cardData": {
    "emvData": {
      "tags": "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
      "trackData": ";4111111111111111=33121019761186800000?",
      "cardSequenceNumber": "01"
    }
  }
}'

3. Contactless Refund

curl --location 'https://apitest.valorvpc.com/payment/refund' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "refund",
  "card": "debit",
  "commerceIndicator": "retail",
  "amount": "100.00",
  "entryMode": "contactless",
  "pin_block": "5D5FA5E5B448F33B",
  "pin_format": "0",
  "ksn": "FFFF1B1D140000200001",
  "cardData": {
    "emvData": {
      "tags": "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
      "trackData": ";4111111111111111=33121019761186800000?",
      "cardSequenceNumber": "01"
    }
  }
}'

Important Notes:

Direct refunds do not require a ref_id from a previous transaction
All the same entry mode requirements apply as with sale transactions

Balance Inquiry

Balance inquiry allows checking available funds on a debit card without performing a transaction. No amount is required.

1. Contactless Balance Inquiry

curl --location 'https://apitest.valorvpc.com/payment/balance-inquiry' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "balance_inquiry",
  "commerceIndicator": "retail",
  "entryMode": "contactless",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "emvData": {
      "tags": "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
      "trackData": ";4111111111111111=33121019761186800000?",
      "cardSequenceNumber": "01"
    }
  }
}'

Example Response:

{
  "responseCode": "00",
  "ref_id": "273d4aa1-fc67-49ac-83b4-de7b707c37de",
  "status": "AUTHORIZED",
  "creatorName": "VALOR",
  "txn_type": "balance_inquiry",
  "tran_no": 8,
  "batch_no": "3",
  "balance": {
    "amount": "+20.00",
    "accountType": "40",
    "amountType": "02"
  },
  "authCode": "831000",
  "reference": "123456882138",
  "cardInformation": {
    "maskedPan": "411111XXXXXX1111",
    "expiryDate": "1233"
  },
  "created": "2025-12-04T18:53:54Z"
}

Response Fields:

responseCode: "00" indicates success
balance.amount: Available balance (+ indicates positive, - indicates negative)
balance.accountType: Account type code ("10" = Savings, "20" or "40" = Checking)
balance.amountType: "02" indicates ledger balance
cardInformation.maskedPan: Masked card number for display

2. Contact Balance Inquiry

curl --location 'https://apitest.valorvpc.com/payment/balance-inquiry' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "balance_inquiry",
  "commerceIndicator": "retail",
  "entryMode": "contact",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "emvData": {
      "tags": "9F3303204000950500000000009F3704518823719F100706011103A000009F26081E1756ED0E2134E29F36020015820200009C01009F1A0208409A030006219F02060000000020005F2A0208409F0306000000000000",
      "trackData": ";4111111111111111=33121019761186800000?",
      "cardSequenceNumber": "01"
    }
  }
}'

3. Swiped Balance Inquiry

curl --location 'https://apitest.valorvpc.com/payment/balance-inquiry' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "balance_inquiry",
  "commerceIndicator": "retail",
  "entryMode": "swiped",
  "pin_block": "52F20658C04DB351",
  "pin_format": "1",
  "ksn": "FFFF1B1D140000000005",
  "cardData": {
    "trackData": ";4111111111111111=33121019761186800000?"
  }
}'

Important Notes:

No amount field is required for balance inquiry
Response includes current account balance
Multiple account types may be returned (checking, savings)

Transaction Reversal

Transaction reversal (timeout reversal) is used to reverse a PIN Debit transaction when the terminal doesn't receive a response within the expected timeframe. This prevents duplicate charges.

PIN Debit Reversal Request

curl --location 'https://apitest.valorvpc.com/payment/txn-timeout' \
--header 'Content-Type: application/json' \
--header 'X-App-Key: a3c35b32-9fa2-496c-9412-78b136456c63' \
--data '{
  "merchantId": "omW7IDQgm1wcUoi",
  "terminalId": "10001458",
  "paymentType": "txn_timeout",
  "card": "debit",
  "amount": "100",
  "ref_id": "da8b8b9f-ae8e-4940-bd50-ea03afd72423"
}'

Required Fields:

paymentType: "txn_timeout" - Indicates a reversal request
card: "debit" - Card type
ref_id: Reference ID from the original transaction to reverse
amount: Original transaction amount (must match exactly)

Important Notes:

Reversals must be sent within a specific time window (typically 24 hours)
The ref_id must match the original transaction's reference ID
Amount must match the original transaction amount exactly

Field Validations

Required Fields for PIN Debit Transactions

Sale/Refund Transactions

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`sale`, `refund`	Transaction type
`amount`	Yes	String/Number	Amount in USD (e.g., "100" or "100.00")
`entryMode`	Yes	`contactless`, `contact`, `swiped`	Card entry method
`card`	Yes	`debit`	Card type
`commerceIndicator`	Yes	`retail`	Transaction environment
`cardData`	Yes	Object	Card information

Balance Inquiry

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`balance_inquiry`	Transaction type
`commerceIndicator`	Yes	`retail`	Transaction environment
`entryMode`	Yes	`contactless`, `contact`, `swiped`	Card entry method
`cardData`	Yes	Object	Card information

Transaction Reversal

Field	Required	Format	Description
`merchantId`	Yes	String	Merchant identifier
`terminalId`	Yes	String	Terminal identifier
`paymentType`	Yes	`txn_timeout`	Reversal transaction type
`card`	Yes	`debit`	Card type
`amount`	Yes	String/Number	Original transaction amount
`ref_id`	Yes	UUID	Reference ID from original transaction

Card Data Validations by Entry Mode

Contactless Entry Mode

Required Fields:

{
  "cardData": {
    "emvData": {
      "tags": "string", // EMV chip data tags (required)
      "trackData": "string", // Track 2 equivalent data (required)
      "cardSequenceNumber": "string" // 2-digit sequence number (required)
    }
  }
}

tags: Hexadecimal string containing EMV tag data from contactless transaction
trackData: Format ;[PAN]=[Expiry][Service Code][Discretionary Data]?

Contact Entry Mode

Required Fields:

{
  "cardData": {
    "emvData": {
      "tags": "string", // EMV chip data tags (required)
      "trackData": "string" // Track 2 equivalent data (required)
    }
  }
}

tags: Hexadecimal string containing EMV tag data from chip
trackData: Format ;[PAN]=[Expiry][Service Code][Discretionary Data]?

Swiped Entry Mode

Required Fields:

{
  "cardData": {
    "trackData": "string" // Track 2 data (required)
  }
}

trackData: Format ;[PAN]=[Expiry][Service Code][Discretionary Data]?
No EMV data for swiped transactions

PIN Block Validations

PIN Block: Encrypted PIN data in hexadecimal format
PIN Format:
- "0": ISO Format 0 - Commonly used for contactless and contact (EMV) transactions
- "1": ISO Format 1 - Commonly used for swiped (magnetic stripe) transactions
KSN (Key Serial Number): Unique identifier for the encryption key used in DUKPT key management
- Format: Hexadecimal string
- Used to derive the transaction key for PIN decryption

Amount Validations

Must be a positive number greater than zero
Maximum 2 decimal places
Minimum amount: $0.01
Maximum amount: Varies by merchant configuration (typically $999,999.99)
Format: Can be string ("100" or "100.00") or number (100)
Not required for balance inquiry transactions

Entry Mode Rules

Entry Mode	Description	Security Level	When to Use
`contactless`	NFC/tap payment	High (EMV)	Card supports contactless, amount under limit
`contact`	Chip insert	High (EMV)	Card has chip, preferred method
`swiped`	Magnetic stripe	Lower	Chip not readable or card has no chip

Best Practice: Always prefer contactless or contact (EMV) over swiped for better security and fraud protection.

Response Codes

Code	Status	Description	Action
`00`	AUTHORIZED	Transaction approved	Complete transaction
`05`	DECLINED	Do not honor	Request different payment method
`51`	DECLINED	Insufficient funds	Request different payment method
`54`	DECLINED	Expired card	Request different payment method
`55`	DECLINED	Incorrect PIN	Allow customer to retry (max 3 attempts)
`61`	DECLINED	Exceeds withdrawal limit	Request lower amount or different card
`91`	DECLINED	Issuer unavailable	Retry or use different payment method

Account Type Codes (Balance Inquiry Response)

Code	Account Type	Description
`10`	Savings	Savings account
`20`	Checking	Checking account
`40`	Checking	Checking account (alternate code)

API Endpoint Reference

Base URL

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

Authentication

All requests require the X-App-Key header:

X-App-Key: your-app-key-here

Endpoints

Endpoint	Method	Description
`/payment/sale`	POST	Process PIN Debit sale transaction
`/payment/refund`	POST	Process PIN Debit refund transaction
`/payment/balance-inquiry`	POST	Check account balance
`/payment/txn-timeout`	POST	Reverse transaction (timeout)

Headers

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

Summary

PIN Debit payment processing requires:

Entry Mode Support: Contactless, contact (chip), and swiped (magnetic stripe)
Card Data: EMV data for chip transactions, track data for swiped
Reversals: Timeout reversal capability for failed transactions
Balance Inquiry: Check available funds without processing a transaction