Card Transactions
Overview
You can create CARD transactions via POST /v1/transaction. Common scenarios are shown below.
Resource Access
Production (api.ahrvo.network)
POST https://api.ahrvo.network/banking/us2/v1/customer/id/{customerId}/transaction
Staging (gateway.ahrvo.network)
POST https://gateway.ahrvo.network/banking/us2/v1/customer/id/{customerId}/transaction
note
Each request below shows only the minimal required fields. Supply additional fields (e.g., Level-2/3 data, funding.tags, etc.) as needed for your program.
One-Time Collect — Third-Party → Ahrvo (CARD, auto-capture)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"amountDetails": {
"tipAmount": "{tipAmount}",
"surchargeAmount": "{surchargeAmount}",
"originalAmount": "{originalAmount}"
},
"method": "CARD",
"purpose": "{purpose}",
"isAutoCapture": true,
"funding": { "tags": { "type": "Trust" } },
"source": {
"card": {
"form": "Plastic",
"holderName": "{holderName}",
"cardNumber": "{cardNumber}",
"expiryMonth": "{expiryMonth}",
"expiryYear": "{expiryYear}",
"cvv": "{cvv}",
"accountType": "SAVINGS",
"avs": {
"zip": "{zip}",
"addressLine1": "{addressLine1}",
"firstName": "{firstName}",
"middleName": "{middleName}",
"lastName": "{lastName}",
"phone": "{phone}",
"email": "{email}"
},
"cardHolder": {
"name": "{cardHolderName}",
"firstName": "{cardHolderFirstName}",
"lastName": "{cardHolderLastName}",
"ipAddress": "{ipAddress}",
"hostName": "{hostName}",
"browserType": "{browserType}",
"phone": "{cardHolderPhone}",
"email": "{cardHolderEmail}",
"number": "{cardHolderNumber}"
},
"billingAddress": {
"addressLine1": "{billingAddressLine1}",
"city": "{billingCity}",
"state": "{billingState}",
"zip": "{billingZip}",
"country": "{billingCountry}"
}
}
},
"type": "REGULAR",
"processingDetail": {
"statementDescriptor": "{statementDescriptor}",
"businessApplication": "{businessApplication}",
"device": {
"posId": "{posId}",
"type": "{deviceType}",
"accountCaptureMethod": "{accountCaptureMethod}",
"cardPresent": "{cardPresent}",
"cardholderPresence": "{cardholderPresence}",
"attendance": "{attendance}",
"location": "{deviceLocation}",
"catLevel": "{catLevel}",
"transactionSecurity": "{transactionSecurity}",
"transactionStatus": "{transactionStatus}",
"partialApprovalSupport": "{partialApprovalSupport}"
},
"merchant": { "id": "{merchantId}" },
"order": {
"invoice": {
"number": "{invoiceNumber}",
"discountRate": "{discountRate}",
"discountAmount": "{discountAmount}",
"taxAmount": "{taxAmount}",
"taxRate": "{taxRate}",
"taxExempt": "{taxExempt}",
"shipmentDetail": {
"freightTaxRate": "{freightTaxRate}",
"destinationPostalCode": "{destinationPostalCode}",
"sourcePostalCode": "{sourcePostalCode}",
"dutyAmount": "{dutyAmount}",
"freightAmount": "{freightAmount}",
"freightTaxAmount": "{freightTaxAmount}",
"address": {
"country": "{shippingCountry}",
"addressLine1": "{shippingAddressLine1}",
"addressLine2": "{shippingAddressLine2}",
"city": "{shippingCity}",
"state": "{shippingState}",
"zip": "{shippingZip}"
}
},
"lineItem": [
{
"commodityCode": "{commodityCode1}",
"description": "{description1}",
"productCode": "{productCode1}",
"unitOfMeasure": "{unitOfMeasure1}",
"quantity": "{quantity1}",
"unitCost": "{unitCost1}",
"discountRate": "{discountRate1}",
"discountAmount": "{discountAmount1}",
"taxRate": "{taxRate1}",
"taxAmount": "{taxAmount1}",
"dutyAmount": "{dutyAmount1}",
"extendedAmount": "{extendedAmount1}"
},
{
"commodityCode": "{commodityCode2}",
"description": "{description2}",
"productCode": "{productCode2}",
"unitOfMeasure": "{unitOfMeasure2}",
"quantity": "{quantity2}",
"unitCost": "{unitCost2}",
"discountRate": "{discountRate2}",
"discountAmount": "{discountAmount2}",
"taxRate": "{taxRate2}",
"taxAmount": "{taxAmount2}",
"dutyAmount": "{dutyAmount2}",
"extendedAmount": "{extendedAmount2}"
}
]
},
"lodging": {
"purchaseId": "{purchaseId}",
"folio": "{folio}",
"customerPhone": "{customerPhone}",
"recordCharge": "{recordCharge}",
"propertyPhone": "{propertyPhone}",
"programCode": "{programCode}",
"rooms": [
{ "checkin": "{checkin1}", "checkout": "{checkout1}", "amount": "{roomAmount1}", "duration": "{duration1}" },
{ "checkin": "{checkin2}", "checkout": "{checkout2}", "amount": "{roomAmount2}", "duration": "{duration2}" }
]
}
}
}
}
Collect — Third-Party (Token) → Ahrvo
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"type": "REGULAR",
"method": "CARD",
"processingDetail": {
"merchant": { "id": "{merchantId}" },
"statementDescriptor": "{statementDescriptor}"
},
"source": { "card": { "token": "{cardToken}" } },
"destination": { "account": { "id": "{destinationAccountId}" } },
"amount": "{amount}",
"purpose": "{purpose}"
}
Collect — Contact → Ahrvo (CARD)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"method": "CARD",
"type": "REGULAR",
"amount": "31",
"allowDuplicate": true,
"purpose": "services",
"source": {
"contact": {
"id": 925,
"card": { "id": 1897, "cvv": 323 }
}
},
"destination": { "account": { "id": 4019941 } },
"processingDetail": {
"merchant": { "id": 4001309 },
"statementDescriptor": "services"
}
}
Collect — Pre-Existing Card Entity
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"externalId": "EID188118842194616366200",
"amount": "100.00",
"allowDuplicate": true,
"method": "CARD",
"type": "REGULAR",
"purpose": "Fee",
"source": { "card": { "id": "529" } },
"destination": { "account": { "id": "4000407" } },
"processingDetail": {
"merchant": { "id": 4001995 },
"location": { "id": 2062 },
"statementDescriptor": "services"
},
"comment": "Deposit created"
}
Ad-hoc Refund — Card (No Prior Sale)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"type": "REFUND",
"reason": "RETAIN_CUSTOMER",
"amount": "12.00",
"method": "CARD",
"processingDetail": {
"merchant": { "id": "4005163" }
},
"purpose": "test transaction collect",
"destination": {
"card": {
"holderName": "test",
"cardNumber": "378282246310005",
"expiryMonth": "3",
"expiryYear": "2029",
"cvv": "8378",
"billingAddress": {
"addressLine1": "Street53",
"city": "Alpharetta",
"state": "GA",
"zip": "30004",
"country": "USA"
}
}
}
}
Sale — Terminal (Amount)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"type": "REGULAR",
"amount": "25.02",
"method": "CARD",
"processingDetail": {
"merchant": { "id": "4007497" },
"terminal": { "id": "DA08333B-CBA7-440A-943D-49813C51C793" }
},
"purpose": "Terminal Work Purpose",
"isAutoCapture": true
}
Sale — Terminal (Original Amount)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"type": "REGULAR",
"method": "CARD",
"processingDetail": {
"merchant": { "id": "4000759" },
"terminal": { "id": "D3203595-E861-4F65-8EE8-AE6C95A2B47B" }
},
"amountDetails": { "originalAmount": "100" },
"isAutoCapture": true,
"purpose": "test ekam"
}
Auth — Terminal (No Capture)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
{
"type": "REGULAR",
"amount": "25.02",
"method": "CARD",
"processingDetail": {
"merchant": { "id": "4007497" },
"terminal": { "id": "DA08333B-CBA7-440A-943D-49813C51C793" }
},
"purpose": "Terminal Work Purpose",
"isAutoCapture": false
}
Refund — Terminal (No Prior Sale)
POST /banking/us2/v1/transaction
Host: <hostname>
Authorization: Bearer <JWT token>
x-api-key: {apiKey}
Content-Type: application/json
"type": "REFUND",
"amount": "5.02",
"method": "CARD",
"processingDetail": {
"merchant": { "id": "4007497" },
"terminal": { "id": "DA08333B-CBA7-440A-943D-49813C51C793" }
},
"purpose": "Terminal Work Purpose"
}