Procare Pay Integration Service

Complete API Documentation for Payment Processing

Welcome to the Integration Service API

The Procare Pay Integration Service is a comprehensive RESTful API that enables secure payment processing, customer profile management, and transaction handling for credit card and ACH (bank account) payments. This service is designed to help you integrate payment capabilities into your applications while maintaining the highest standards of security and PCI DSS compliance.

What Can You Do With This API?

  • Process Payments: Accept credit card and ACH payments, process refunds, and handle returns
  • Manage Customer Profiles: Create and manage payor profiles that store encrypted payment methods for recurring billing
  • Secure Data Handling: Use RSA public key encryption to protect sensitive payment data
  • Card Validation: Look up BIN (Bank Identification Number) information to identify card types and surcharge rules
  • Transaction Management: Search, retrieve, and update transaction details and custom attributes
  • Merchant Information: Access merchant capabilities, limits, and configuration details
Security First: All payment card numbers and bank account numbers must be encrypted using public encryption keys before transmission. Never send unencrypted sensitive payment data. This API is designed to help you maintain PCI DSS compliance.

Getting Started

📚

RESTful Basics

New to RESTful APIs? Start here to understand the fundamentals of REST architecture and HTTP methods.

Read Guide
🔐

Authentication

Learn how to authenticate using AWS Cognito OAuth2 and obtain bearer tokens for API access.

View Authentication
⚡

Integration Best Practices

Essential guide covering payment flows, error handling, security, and resilient coding practices for production integrations.

View Best Practices

API Reference Documentation

Documentation Format: Each endpoint is documented with detailed explanations, request/response examples, and code samples in C#, VB.NET, Java, and Ruby. Click on any link below to view the full documentation for that endpoint.

🔑 Encryption Keys

Retrieve public encryption keys for securing sensitive payment data. Always encrypt credit card numbers, bank account numbers, and CVV codes before sending to the API.

🏢 Merchant Information

Access merchant configuration, capabilities, transaction limits, and funding model information.

💳 BIN Lookup (Card Identification)

Look up Bank Identification Numbers to determine card brand, issuer, and surcharge eligibility.

👤 Payor Management (Customer Profiles)

Create and manage customer payment profiles (payors) that can store multiple payment methods for recurring billing or one-click checkout.

Payor Profiles

Saved Payment Methods

💰 Transaction Processing

Process payments, handle refunds and returns, search transaction history, and manage transaction data.

📅 Holidays

Retrieve upcoming U.S. banking holidays that may affect ACH payment processing and settlement timing.

🏥 Service Status & Health Checks

Monitor service availability and check the health of downstream dependencies. These endpoints do not require authentication.

Common Integration Workflows

1. First-Time Payment with Profile Creation

  1. Authenticate to get bearer token
  2. Get PAN encryption key
  3. Get SAD encryption key (if collecting CVV)
  4. Encrypt payment card number with PAN key
  5. Encrypt CVV with SAD key (use immediately, never store)
  6. Create payor profile with encrypted card
  7. Process transaction using saved payment method ID

2. Recurring Payment (Existing Customer)

  1. Authenticate to get bearer token
  2. Look up payor by your customer ID
  3. Get payment methods and find default
  4. Process transaction using saved payment method ID

3. Update Expired Card

  1. Get PAN encryption key
  2. Encrypt new card number with PAN key
  3. Add new payment method with setAsDefault: true
  4. Delete old expired card

4. Process Refund

  1. Search for original transaction by order ID or transaction ID
  2. Initiate refund with original transaction ID and amount

Best Practices & Security

PCI DSS Compliance:
  • Never log or store unencrypted card numbers or bank account numbers
  • Never store CVV codes, even encrypted (use immediately and discard)
  • Always use HTTPS for all API communications
  • Rotate and refresh encryption keys every 4-6 hours
  • Clear sensitive data from memory immediately after encryption
  • Validate and sanitize all input data
Performance Tips:
  • Cache PAN and SAD encryption keys for 4-6 hours to reduce API calls
  • Use bulk BIN lookup endpoint when validating multiple cards
  • Implement retry logic with exponential backoff for 408 timeout errors
  • Use pagination parameters when searching large transaction datasets
  • Store payor IDs and saved payment method IDs in your database for quick lookup
Error Handling:
  • 400 Bad Request: Validation error - check request format and required fields
  • 401 Unauthorized: Token expired or invalid - re-authenticate
  • 404 Not Found: Resource doesn't exist - verify IDs and check if resource was deleted
  • 408 Request Timeout: Retry with exponential backoff
  • 500 Internal Server Error: Server-side issue - log error and contact support if persistent

Code Examples

Every endpoint in this documentation includes complete, working code examples in multiple programming languages:

  • C# - .NET Core/Framework with HttpClient and RSA encryption
  • VB.NET - Visual Basic .NET with full async/await support
  • Java - Java 11+ with HttpClient and Jackson JSON
  • Ruby - Ruby with Net::HTTP and OpenSSL

Each code example includes authentication, encryption (where applicable), error handling, and helper methods to make integration as straightforward as possible.

Support & Additional Resources

For technical support, questions, or issues with the API:

  • Contact: Procare Software, LLC
  • Base URL: /rest (relative to your environment's base URL)