GoodFunds Gateway API

Secure, RESTful payment processing API

Production Ready v1.6.0 Last Updated: 2026

Quick Start

Make your first API call in seconds:

JSON Request 
{
  "charge_type": "ccauthcapture",
  "creditcard": {
    "creditcard_number": "4111111111111111",
    "creditcard_exp_month": 12,
    "creditcard_exp_year": 2025,
    "creditcard_cvv": 123
  },
  "amount": "100.00"
}

Base URLs

Sandbox https://demo.goodfundsgateway.com/api/ Test Transactions
Production https://live.goodfundsgateway.com/api/ Live Transactions

Get Started

Don't have an account yet? Request access to our sandbox environment to start testing the API.

Request Sandbox Access

Authentication

All API requests require authentication via request headers

API Credentials

You must include the following headers in every request:

Header Description Example
svs-api-id Your unique API identifier UPB0W66B96PCIXU45PRI
svs-api-key Your secret API key (keep secure!) 192QP4J8K4LI5M58P4VDCQN5I2GECDEEHMYPXQKJ
Security Warning: Never expose your API credentials in client-side code or public repositories. Always use server-side code to make API calls.

Authentication Error Example

If authentication fails, you'll receive a 401 error:

JSON Response 
{
  "status": "error",
  "errorMessage": {
    "response_code": 401,
    "message": "Invalid API credentials",
    "details": "The provided API key does not match the API ID"
  }
}

Testing Guide

Test data for sandbox environment

Credit Card Test Numbers

Use these test credit card numbers in sandbox mode. Different gateways have different test card requirements.

Card Type Card Number Gateway Support Notes
Visa 4111111111111111 All Gateways Standard test card
Mastercard 5555555555554444 All Gateways Standard test card
Discover 6011111111111117 All Gateways Standard test card
Amex 378282246310005 Converge, Authorize.net 15-digit Amex test card
JCB 3566002020360505 Converge, Authorize.net JCB test card
Diners Club 30569309025904 Converge Only 14-digit Diners Club test card

Credit Card Test Scenarios

Scenario Card Number Amount Expected Response
Approved 4111111111111111 Any Approved
Declined 4000000000000002 Any Declined - Card declined
Insufficient Funds 4000000000000003 Any Declined - Insufficient funds
AVS Mismatch 4000000000000004 Any AVS mismatch
CVV Mismatch 4000000000000005 Any CVV mismatch
Expired Card 4000000000000006 Any Expired card

eCheck / ACH Test Accounts

Converge ACH Test Accounts

Account Type Routing Number Account Number Result
Valid Account 122105278 0000000016 Approved
Valid Account 321174851 9900000003 Approved
Invalid Account 122105278 0000000001 Declined
Invalid Routing 111111111 0000000016 Invalid Routing Number

Linked2Pay (AvidiaPay) ACH Test Accounts

Account Type Routing Number Account Number Result
Valid Checking 122105278 0000000016 Approved
Valid Checking 321174851 9900000003 Approved
Valid Savings 122105278 0000000010 Approved
Invalid Account 122105278 0000000001 Declined

Jack Henry SmartPay ACH Test Accounts

Important: Jack Henry requires specific test accounts. Use only these test accounts.
Account Type Routing Number Account Number Result
Valid Checking 053100244 123456789 Approved
Valid Checking 053100244 987654321 Approved
Valid Savings 053100244 111111111 Approved
Declined 053100244 000000000 Declined
Invalid Routing 111111111 123456789 Invalid Routing

Common Test Scenarios by Gateway

Gateway Card Test ACH Test Notes
Converge ✓ Full Support ✓ Full Support All test cards work. All ACH accounts work.
Authorize.net ✓ Full Support Limited Use standard test cards. ACH limited.
Linked2Pay (AvidiaPay) ✓ Full Support ✓ Full Support All test cards work. All ACH accounts work.
Jack Henry SmartPay Limited Limited Use specific test accounts only

Credit Card Expiration Dates

Use these expiration dates for testing:

  • Future Date: 12/2028 or any date in the future
  • Expired Date: 12/2020 - Will trigger expired card response
  • Current Month: Use current month + 1 year for valid transactions

CVV Test Values

  • Valid CVV: 123 (Visa/Mastercard/Discover) or 1234 (Amex)
  • Invalid CVV: 999 - Will trigger CVV mismatch

Payment Methods

Securely store and manage payment methods

POST /paymentmethod.json Required

Store a credit card or eCheck for future use. Credit cards are tokenized for security.

Content-Type application/json
Authentication Required
Rate Limit 100 requests/minute

Parameters

Required Parameters
Parameter Type Description Example
creditcard or echeck object Payment method details See examples
customer object Customer information See examples
default integer 1 to set as default payment method 1
gateway_id integer Gateway account ID for tokenization 123

Example Requests

JSON Request 
{
  "gateway_id": 123,
  "customer": {
    "internal_id": "CUST-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "555-123-4567"
  },
  "billto": {
    "address_1": "123 Main St",
    "city": "San Diego",
    "state": "CA",
    "postal_code": "92101",
    "country": "US"
  },
  "shipto": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Main St",
    "city": "San Diego",
    "state": "CA",
    "postal_code": "92101",
    "country": "US"
  },
  "creditcard": {
    "creditcard_name": "John Doe",
    "creditcard_number": "4111111111111111",
    "creditcard_type": "VISA",
    "creditcard_exp_month": 12,
    "creditcard_exp_year": 2025,
    "creditcard_cvv": 123
  },
  "default": 1,
  "level3": {
    "ship_from_postal_code": "92106",
    "destination_postal_code": "92101"
  }
}
JSON Request 
{
  "gateway_id": 456,
  "customer": {
    "internal_id": "CUST-002",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  },
  "billto": {
    "address_1": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001"
  },
  "echeck": {
    "echeck_name": "Jane Smith",
    "echeck_account_number": "9900000003",
    "echeck_routing_number": "321174851",
    "echeck_account_type": 1, // 0 Business 1 Personal
    "echeck_holder_type": 0, // 0 Checking 1 Savings
    "echeck_seccode": "WEB"
  },
  "default": 1
}
JSON Request 
{
  "is_vendor": 1,
  "vendor_id": 1,
  "default": 1,
  "gateway_id": 456,
  "echeck": {
    "echeck_name": "ABC Supplies Inc.",
    "echeck_account_number": "987654321",
    "echeck_routing_number": "053100244",
    "echeck_account_type": 1, // 0 Business 1 Personal
    "echeck_holder_type": 0, // 0 Checking 1 Savings
    "echeck_seccode": "WEB"
  }
}

Success Response

200 OK Success
JSON Response 
{
  "status": "success",
  "successMessage": {
    "response_code": 700,
    "message": {
      "payment_method": {
        "payment_method_id": 12345,
        "card_type": "VISA",
        "last_four": "1111"
      }
    }
  }
}
GET /paymentmethods.json Optional

List all payment methods for a customer.

Query Parameters

Parameter Type Description Example
customer_id integer Filter by customer ID 123
internal_id string Filter by internal ID CUST-001
method_type integer 1=Credit Card, 2=eCheck 1
vendor_id integer Filter vendor payment methods 1

Example Request

cURL 
curl -X GET "https://demo.goodfundsgateway.com/api/paymentmethods.json?customer_id=123&method_type=1" \
  -H "svs-api-id: YOUR_API_ID" \
  -H "svs-api-key: YOUR_API_KEY"

Charges

Process credit card and eCheck transactions

POST /charge.json Required

Process a single transaction. Supports credit card sales, authorizations, and eCheck processing.

Content-Type application/json
Authentication Required
Rate Limit 100 requests/minute

Parameters

Required Parameters
Parameter Type Description Example
charge_type string Transaction type ccauthcapture
amount decimal Transaction amount 100.00
creditcard or echeck object Payment method details See examples
Charge Types
Type Description
ccauthcapture Authorize and capture payment immediately
ccauthorize Authorize payment (capture later)
ccprocesspreauthorize Capture a previously authorized transaction
ecdebit Debit from a checking account
eccredit Credit to a checking account

Example Requests

JSON Request 
{
  "charge_type": "ccauthcapture",
  "gateway_id": 123,
  "customer": {
    "internal_id": "CUST-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "555-123-4567"
  },
  "billto": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Main St",
    "city": "San Diego",
    "state": "CA",
    "postal_code": "92101",
    "country": "US",
    "email": "john@example.com",
    "phone": "555-123-4567"
  },
  "shipto": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "123 Main St",
    "city": "San Diego",
    "state": "CA",
    "postal_code": "92101",
    "country": "US"
  },
  "level2": {
    "invoice_number": "INV-001",
    "salestax": "8.50",
    "po_number": "PO-12345",
    "customer_code": "CUST-001"
  },
  "level3": {
    "ship_from_postal_code": "92106",
    "destination_postal_code": "92101",
    "item_product_code": "PROD-001",
    "item_description": "Product Description",
    "item_quantity": "1",
    "item_extended_amount": "100.00"
  },
  "creditcard": {
    "creditcard_name": "John Doe",
    "creditcard_number": "4111111111111111",
    "creditcard_type": "VISA",
    "creditcard_exp_month": 12,
    "creditcard_exp_year": 2025,
    "creditcard_cvv": 123
  },
  "amount": "100.00"
}
JSON Request 
{
  "charge_type": "ccauthorize",
  "gateway_id": 123,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "billto": {
    "address_1": "123 Main St",
    "city": "San Diego",
    "state": "CA",
    "postal_code": "92101"
  },
  "creditcard": {
    "creditcard_name": "John Doe",
    "creditcard_number": "4111111111111111",
    "creditcard_exp_month": 12,
    "creditcard_exp_year": 2025,
    "creditcard_cvv": 123
  },
  "amount": "100.00"
}
JSON Request 
{
  "charge_type": "ccprocesspreauthorize",
  "gateway_id": 123,
  "amount": "100.00",
  "level2": {
    "invoice_number": "INV-001"
  }
}
JSON Request 
{
  "charge_type": "ecdebit",
  "gateway_id": 456,
  "customer": {
    "internal_id": "CUST-002",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  },
  "billto": {
    "first_name": "Jane",
    "last_name": "Smith",
    "address_1": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US"
  },
  "echeck": {
    "echeck_name": "Jane Smith",
    "echeck_account_number": "9900000003",
    "echeck_routing_number": "321174851",
    "echeck_check_number": "101",
    "echeck_account_type": 1, // 0 Business 1 Personal
    "echeck_holder_type": 0, // 0 Checking 1 Savings
    "echeck_seccode": "WEB",
    "echeck_agree": 1
  },
  "amount": "250.00"
}
JSON Request 
{
  "charge_type": "ccauthcapture",
  "gateway_id": 123,
  "payment_method_id": 12345,
  "amount": "50.00",
  "creditcard": {
    "creditcard_cvv": 123
  },
  "level2": {
    "invoice_number": "INV-002"
  }
}

Responses

200 OK Success
JSON Response 
{
  "status": "success",
  "successMessage": {
    "response_code": 1,
    "message": {
      "charge": {
        "success": true,
        "charge_id": 98765,
        "trans_id": "TXN-20260615-ABCDEF",
        "approval_code": "ABC123",
        "card_number": "411111******1111",
        "amount": "100.00",
        "raw_data": {
          "processor_response": "Approved",
          "auth_code": "ABC123"
        }
      }
    }
  }
}
402 Payment Required Declined
JSON Response 
{
  "status": "declined",
  "errorMessage": {
    "response_code": 402,
    "message": "Transaction declined",
    "details": {
      "reason": "Insufficient funds",
      "processor_code": "51",
      "processor_message": "Insufficient funds"
    }
  }
}
400 Bad Request Validation Error
JSON Response 
{
  "status": "error",
  "errorMessage": {
    "response_code": 400,
    "message": "Missing required field",
    "details": {
      "field": "creditcard_number",
      "description": "Credit card number is required for credit card transactions"
    }
  }
}

Refunds

Process refunds for previous charges

POST /charge.json Refund

Process a refund for a previous charge. Automatically voids if settlement hasn't occurred.

Parameters

Parameter Type Required Description Example
charge_type string Yes Use ccrefund or ecrefund ccrefund
charge_id integer Yes ID of the charge to refund 98765
amount decimal No Amount to refund (defaults to full amount) 50.00
gateway_id integer No Gateway account ID 123

Example Request

JSON Request 
{
  "charge_type": "ccrefund",
  "gateway_id": 123,
  "charge_id": 98765,
  "amount": "50.00"
}

Success Response

200 OK Success
JSON Response 
{
  "status": "success",
  "successMessage": {
    "response_code": 1,
    "message": {
      "charge": {
        "success": true,
        "refund_id": 54321,
        "amount_refunded": "50.00"
      }
    }
  }
}

Recurring Payments

Set up and manage automated ACH payments

Note: Recurring payments are only available for ACH processing with specific gateways. Please contact support to enable recurring payments for your account.
POST /setuprecurringcharge.json Required

Set up a recurring ACH payment schedule.

Parameters

Parameter Type Required Description Example
charge_type string Yes Use ecrecurring ecrecurring
amount decimal Yes Amount for each recurring payment 100.00
schedule object Yes Recurring schedule details See example
echeck object Yes Bank account details See example
Schedule Parameters
Parameter Type Description Example
frequency string monthly, weekly, quarterly, yearly monthly
payment_day integer Day of month or day of week (0=Sun...6=Sat) 15
start_date date Start date (YYYY-MM-DD) 2026-07-01
num_payments string/integer "indefinite" or number of payments indefinite
enabled integer 1=enabled, 0=disabled 1
description string Description of the recurring payment Monthly Subscription

Example Request

JSON Request 
{
  "charge_type": "ecrecurring",
  "gateway_id": 456,
  "customer": {
    "internal_id": "CUST-003",
    "first_name": "Robert",
    "last_name": "Johnson",
    "email": "robert@example.com"
  },
  "billto": {
    "first_name": "Robert",
    "last_name": "Johnson",
    "address_1": "789 Pine St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94101"
  },
  "echeck": {
    "echeck_name": "Robert Johnson",
    "echeck_account_number": "0000000016",
    "echeck_routing_number": "122105278",
    "echeck_account_type": 1, // 0 Business 1 Personal
    "echeck_holder_type": 0, // 0 Checking 1 Savings
    "echeck_seccode": "PPD",
    "echeck_agree": 1
  },
  "schedule": {
    "frequency": "monthly",
    "payment_day": 15,
    "start_date": "2026-07-15",
    "num_payments": "indefinite",
    "enabled": 1,
    "description": "Monthly Subscription Payment"
  },
  "amount": "100.00"
}

Success Response

200 OK Success
JSON Response 
{
  "status": "success",
  "successMessage": {
    "response_code": 1,
    "message": {
      "recurring": {
        "response_code": 100,
        "response_text": "Recurring Payment created.",
        "success": true,
        "recur_id": 12345,
        "amount": "100.00"
      }
    }
  }
}
POST /stoprecurringcharge.json Cancel

Cancel an active recurring payment.

Parameters

Parameter Type Required Description Example
charge_type string Yes Use ecstoprecurring ecstoprecurring
recur_id integer Yes Recurring payment ID 12345
reason string No Reason for cancellation Customer requested

Example Request

JSON Request 
{
  "charge_type": "ecstoprecurring",
  "gateway_id": 456,
  "recur_id": 12345,
  "reason": "Customer requested cancellation"
}

Vendors

Manage vendor information for disbursements

POST /vendor.json Required

Create a new vendor record for ACH disbursements.

Parameters

Parameter Type Required Description Example
internal_id string Yes Your unique vendor identifier VENDOR-001
company_name string Yes Legal business name ABC Supplies Inc.
tax_id string No Tax ID / EIN number 12-3456789
email string No Vendor email address billing@abcsupplies.com
phone string No Vendor phone number 555-123-4567
status string No active or inactive active

Example Request

JSON Request 
{
  "internal_id": "VENDOR-001",
  "company_name": "ABC Supplies Inc.",
  "tax_id": "12-3456789",
  "email": "billing@abcsupplies.com",
  "phone": "555-123-4567",
  "address_1": "123 Business Road",
  "address_2": "Suite 200",
  "city": "Anywhere",
  "state": "CA",
  "postal_code": "90210",
  "country": "USA",
  "contact_name": "John Smith",
  "contact_email": "john@abcsupplies.com",
  "contact_phone": "555-123-4568",
  "payment_terms": "NET30",
  "status": "active"
}
GET /vendors.json Optional

List all vendors with optional filters.

Query Parameters

Parameter Type Description Example
internal_id string Filter by internal ID VENDOR-001
company_name string Filter by company name (partial match) ABC Supplies
email string Filter by email @abcsupplies.com
status string active, inactive, suspended active

Disbursements

Process vendor payments via ACH credit

POST /disbursement.json Required

Create a disbursement (vendor payment) via ACH credit.

Parameters

Parameter Type Required Description Example
vendor_id integer No Vendor ID (required if no internal_id) 1
vendor_internal_id string No Vendor internal ID (required if no vendor_id) VENDOR-001
payment_method_id integer Yes Vendor eCheck payment method ID 5
amount decimal Yes Payment amount 1500.00
description string No Payment description Office supplies - Q4
invoice_number string No Vendor invoice number INV-2024-001
scheduled_date date No Schedule date (YYYY-MM-DD) 2026-07-15

Example Request

JSON Request 
{
  "vendor_id": 1,
  "payment_method_id": 5,
  "amount": "1500.00",
  "currency": "USD",
  "gateway_id": 456,
  "charge_type": "disbursement",
  "internal_id": "PO-12345",
  "invoice_number": "INV-2024-001",
  "purchase_order": "PO-12345",
  "description": "Office supplies - Q4",
  "memo": "Approved by John",
  "scheduled_date": "2026-07-15"
}

Success Response

200 OK Success
JSON Response 
{
  "status": "success",
  "successMessage": {
    "response_code": 700,
    "message": {
      "disbursement": {
        "success": true,
        "disbursement_id": 12345,
        "transaction_id": "TXN-20260615-ABCDEF",
        "status": "pending",
        "vendor_id": 1,
        "vendor_name": "ABC Supplies Inc.",
        "amount": "1500.00"
      }
    }
  }
}

Transaction Status

Check the status of ACH transactions

GET /transaction.json Optional

Check the status of an ACH transaction, including returns and settlements.

Parameters

Parameter Type Required Description Example
gateway_id integer Yes Gateway account ID 456
charge_id integer Yes Charge ID to check 98765

Example Request

cURL 
curl -X GET "https://demo.goodfundsgateway.com/api/transaction.json/456/98765" \
  -H "svs-api-id: YOUR_API_ID" \
  -H "svs-api-key: YOUR_API_KEY"

Success Response

200 OK Success
JSON Response 
{
  "status": "success",
  "successMessage": {
    "response_code": 707,
    "message": {
      "transaction": {
        "success": true,
        "charge_id": 98765,
        "trans_id": "TXN-20260615-ABCDEF",
        "trans_status": "Returned",
        "return_code": "R05",
        "return_reason": "Unauthorized debit to consumer account"
      }
    }
  }
}

Common ACH Return Codes

Return Code Description Solution
R01 Insufficient Funds Customer needs to fund account
R02 Account Closed Customer needs to provide new account
R03 No Account/Unable to Locate Verify account details
R04 Invalid Account Number Customer provided wrong account number
R05 Unauthorized Debit Customer disputes the charge
R08 Payment Stop Customer placed a stop payment
R10 Customer Advises Not Authorized Customer disputes authorization

Error Codes

Common API error responses and their meanings

HTTP Status Response Code Message Description Solution
400 1001 Missing Required Field Required parameter is missing Check request parameters
400 1002 Invalid Field Value Parameter has invalid value Check parameter format
400 1003 Invalid Request Format JSON format is invalid Validate JSON syntax
401 2001 Invalid API Credentials API ID or Key is invalid Verify API credentials
401 2002 Account Suspended Account is suspended Contact support
402 3001 Payment Declined Transaction was declined Use different payment method
402 3002 Insufficient Funds Not enough funds available Customer needs to add funds
402 3003 Card Expired Card expiration date is past Update card information
403 4001 Permission Denied Insufficient permissions Check user permissions
404 5001 Resource Not Found Requested resource doesn't exist Verify resource ID
429 6001 Rate Limit Exceeded Too many requests Reduce request frequency
500 7001 Internal Server Error Server error occurred Contact support
502 7002 Gateway Error Payment gateway connection failed Try again or contact support
Note: Always handle error responses gracefully in your application. Provide clear feedback to users based on the error received.